lutaml 0.9.43 → 0.10.1

data/lib/lutaml/cli/uml/spa_command.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require_relative "../output_formatter"
+require_relative "../../uml"
+
+module Lutaml
+  module Cli
+    module Uml
+      # SpaCommand generates static SPA browser for UML models
+      class SpaCommand
+        attr_reader :options
+
+        def initialize(options = {})
+          @options = options.transform_keys(&:to_sym)
+        end
+
+        def self.add_options_to(thor_class, _method_name) # rubocop:disable Metrics/MethodLength
+          thor_class.long_desc <<-DESC
+          Generate a modern, interactive Single Page Application (SPA) for browsing
+          UML models. Supports both single-file (all-in-one HTML) and multi-file
+          (separate assets) output modes.
+
+          Examples:
+            # Single-file SPA (open directly in browser)
+            lutaml uml build-spa model.lur -o browser.html
+
+            # Multi-file site (for hosting)
+            lutaml uml build-spa model.lur -o dist/ -m multi-file
+
+            # With custom title and minification
+            lutaml uml build-spa model.lur -o dist/ --title "My Model" --minify
+
+            # From QEA file
+            lutaml uml build-spa model.qea -o browser.html
+          DESC
+
+          thor_class.option :output, aliases: "-o", required: true,
+                                     desc: "Output path (file for " \
+                                           "single-file, directory for " \
+                                           "multi-file)"
+          thor_class.option :mode, aliases: "-m", default: "single-file",
+                                   desc: "Output mode: 'single-file' or " \
+                                         "'multi-file'"
+          thor_class.option :title, type: :string, default: "UML Model Browser",
+                                    desc: "Site title"
+          thor_class.option :minify, type: :boolean, default: false,
+                                     desc: "Minify HTML/CSS/JS output"
+          thor_class.option :theme, type: :string, default: "light",
+                                    desc: "Default theme: 'light' or 'dark'"
+        end
+
+        def run(input_path) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          validate_input(input_path)
+
+          mode = determine_mode
+          output_path = validate_output_path(mode)
+
+          OutputFormatter.progress("Loading repository from #{input_path}")
+          repository = load_repository(input_path)
+          OutputFormatter.progress_done
+
+          OutputFormatter.progress("Generating SPA (#{mode} mode)")
+          generate_spa(repository, mode, output_path)
+          OutputFormatter.progress_done
+
+          display_success_message(mode, output_path)
+        rescue StandardError => e
+          OutputFormatter.progress_done(success: false)
+          puts OutputFormatter.error("SPA generation failed: #{e.message}")
+          puts "Backtrace:"
+          puts e.backtrace.first(20).join("\n")
+          raise Thor::Error, "SPA generation failed: #{e.message}"
+        end
+
+        private
+
+        def validate_input(input_path)
+          return if File.exist?(input_path)
+
+          puts OutputFormatter.error("Input file not found: #{input_path}")
+          raise Thor::Error, "Input file not found: #{input_path}"
+        end
+
+        def detect_mode # rubocop:disable Metrics/MethodLength
+          mode_value = options[:mode] || options["mode"] || "single-file"
+
+          case mode_value.downcase
+          when "single-file", "single_file", "single"
+            :single_file
+          when "multi-file", "multi_file", "multi"
+            :multi_file
+          else
+            puts OutputFormatter.error("Invalid mode: #{mode_value}. " \
+                                       "Use 'single-file' or 'multi-file'")
+            raise Thor::Error,
+                  "Invalid mode: #{mode_value}. " \
+                  "Use 'single-file' or 'multi-file'"
+          end
+        end
+
+        def determine_mode # rubocop:disable Metrics/MethodLength
+          mode_value = options[:mode] || "single-file"
+
+          case mode_value.to_s.downcase
+          when "multi-file", "multi_file", "multifile"
+            :multi_file
+          when "single-file", "single_file", "singlefile", ""
+            :single_file
+          else
+            puts OutputFormatter.error("Invalid mode: #{mode_value}. " \
+                                       "Use 'single-file' or 'multi-file'")
+            raise Thor::Error,
+                  "Invalid mode: #{mode_value}. " \
+                  "Use 'single-file' or 'multi-file'"
+          end
+        end
+
+        def validate_output_path(mode) # rubocop:disable Metrics/MethodLength
+          output = options[:output]
+
+          # For multi-file mode, ensure output is a directory
+          if mode == :multi_file && File.extname(output) != ""
+            puts OutputFormatter.colorize(
+              "Warning: Multi-file mode requires directory output", :yellow
+            )
+            output_dir = File.dirname(output)
+            puts "Using directory: #{output_dir}"
+            output_dir
+          else
+            output
+          end
+        end
+
+        def load_repository(path)
+          ext = File.extname(path).downcase
+
+          case ext
+          when ".lur"
+            load_from_lur(path)
+          when ".qea"
+            load_from_qea(path)
+          else
+            raise "Unsupported file type: #{ext}. Expected .lur or .qea"
+          end
+        end
+
+        def load_from_lur(path)
+          Lutaml::UmlRepository::Repository.from_package(path)
+        end
+
+        def load_from_qea(path)
+          require_relative "../../qea"
+
+          # Load QEA database
+          qea_db = Lutaml::Qea::Services::DatabaseLoader.new(path).load
+
+          # Convert to UML Document using factory
+          factory = Lutaml::Qea::Factory::EaToUmlFactory.new(qea_db)
+          document = factory.create_document
+
+          # Create repository from document
+          Lutaml::UmlRepository::Repository.new(document: document)
+        end
+
+        def generate_spa(repository, mode, output_path)
+          generation_options = {
+            mode: mode,
+            output: output_path,
+            title: options[:title] || "UML Model Browser",
+            minify: options[:minify] || false,
+            theme: options[:theme] || "light",
+          }
+
+          Lutaml::UmlRepository::StaticSite.generate(repository,
+                                                     generation_options)
+        end
+
+        def display_success_message(mode, output_path) # rubocop:disable Metrics/MethodLength
+          puts ""
+          if mode == :single_file
+            size_mb = File.size(output_path) / 1024.0 / 1024.0
+            puts OutputFormatter.success(
+              "Generated single-file SPA: #{output_path} " \
+              "(#{'%.2f' % size_mb} MB)",
+            )
+            puts OutputFormatter.colorize("Open in browser to view", :cyan)
+          else
+            puts OutputFormatter.success(
+              "Generated multi-file site in: #{output_path}",
+            )
+            puts OutputFormatter.colorize(
+              "Open #{output_path}/index.html in browser", :cyan
+            )
+          end
+        end
+
+        def format_size(bytes)
+          if bytes < 1024
+            "#{bytes} B"
+          elsif bytes < 1024 * 1024
+            "#{'%.2f' % (bytes / 1024.0)} KB"
+          else
+            "#{'%.2f' % (bytes / 1024.0 / 1024.0)} MB"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/cli/uml/stats_command.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "../output_formatter"
+require_relative "shared_helpers"
+
+module Lutaml
+  module Cli
+    module Uml
+      # StatsCommand shows repository statistics
+      class StatsCommand
+        include SharedHelpers
+
+        attr_reader :options
+
+        def initialize(options = {})
+          @options = options.transform_keys(&:to_sym)
+        end
+
+        def self.add_options_to(thor_class, _method_name)
+          thor_class.long_desc <<-DESC
+          Display statistics about the repository or a specific package.
+
+          Examples:
+            lutaml uml stats model.lur                  # Full repository stats
+            lutaml uml stats model.lur --detailed       # Detailed breakdown
+            lutaml uml stats model.lur --type diagrams  # Diagram-specific stats
+          DESC
+
+          thor_class.option :type, type: :string, default: "all",
+                                   desc: "Statistics type " \
+                                         "(packages|classes|diagrams|all)"
+          thor_class.option :detailed, type: :boolean, default: false,
+                                       desc: "Show detailed statistics"
+          thor_class.option :format, type: :string, default: "text",
+                                     desc: "Output format (text|yaml|json)"
+          thor_class.option :lazy, type: :boolean, default: false,
+                                   desc: "Use lazy loading"
+        end
+
+        def run(lur_path, _path = nil) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          repo = load_repository(lur_path, lazy: options[:lazy])
+          statistics = repo.statistics
+
+          if options[:format] == "text"
+            puts OutputFormatter.format_stats(statistics,
+                                              detailed: options[:detailed])
+          else
+            puts OutputFormatter.format(statistics, format: options[:format])
+          end
+        rescue Thor::Error
+          raise
+        rescue ArgumentError => e
+          raise Thor::Error, e.message
+        rescue StandardError => e
+          raise Thor::Error, "Stats command failed: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/cli/uml/tree_command.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "../output_formatter"
+require_relative "shared_helpers"
+
+module Lutaml
+  module Cli
+    module Uml
+      # TreeCommand shows hierarchical tree view
+      class TreeCommand
+        include SharedHelpers
+
+        attr_reader :options
+
+        def initialize(options = {})
+          @options = options.transform_keys(&:to_sym)
+        end
+
+        def self.add_options_to(thor_class, _method_name)
+          thor_class.long_desc <<-DESC
+          Display a tree view of the package hierarchy.
+
+          Examples:
+            lutaml uml tree model.lur                     # Full tree
+            lutaml uml tree model.lur ModelRoot::Core     # Subtree
+            lutaml uml tree model.lur --depth 2           # Limited depth
+          DESC
+
+          thor_class.option :depth, aliases: "-d", type: :numeric,
+                                    desc: "Maximum depth to display"
+          thor_class.option :show_counts, type: :boolean, default: true,
+                                          desc: "Show class and diagram counts"
+          thor_class.option :format, type: :string, default: "text",
+                                     desc: "Output format (text|yaml|json)"
+          thor_class.option :lazy, type: :boolean, default: false,
+                                   desc: "Use lazy loading"
+        end
+
+        def run(lur_path, path = nil) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          unless File.exist?(lur_path)
+            puts OutputFormatter.error("Package file not found: #{lur_path}")
+            raise Thor::Error, "Package file not found: #{lur_path}"
+          end
+
+          path = normalize_path(path)
+          repo = load_repository(lur_path, lazy: options[:lazy])
+          tree_data = repo.package_tree(path, max_depth: options[:depth])
+
+          unless tree_data
+            puts OutputFormatter.error("Package not found: #{path}")
+            raise Thor::Error, "Package not found: #{path}"
+          end
+
+          if options[:format] == "text"
+            puts display_tree_without_root(tree_data,
+                                           show_counts: options[:show_counts])
+          else
+            puts OutputFormatter.format(tree_data, format: options[:format])
+          end
+        end
+
+        private
+
+        def display_tree_without_root(tree_data, show_counts: true) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          name = if tree_data.is_a?(Hash)
+                   tree_data["name"] || tree_data[:name]
+                 end
+
+          if name == "ModelRoot"
+            children = tree_data["children"] || tree_data[:children]
+            if children.is_a?(Array) && !children.empty?
+              children.map do |child|
+                OutputFormatter.format_tree(child, show_counts: show_counts)
+              end.join("\n")
+            else
+              "(empty repository)"
+            end
+          else
+            OutputFormatter.format_tree(tree_data, show_counts: show_counts)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/cli/uml/validate_command.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require_relative "../output_formatter"
+module Lutaml
+  module Cli
+    module Uml
+      # ValidateCommand validates LUR packages or QEA files
+      class ValidateCommand
+        attr_reader :options
+
+        def initialize(options = {})
+          @options = options.transform_keys(&:to_sym)
+        end
+
+        def self.add_options_to(thor_class, _method_name) # rubocop:disable Metrics/MethodLength
+          thor_class.long_desc <<-DESC
+          Validate a LUR package or QEA file for consistency and completeness.
+
+          Auto-detects file type:
+          - .lur files: Validate LUR package structure
+          - .qea files: Validate QEA file structure and integrity
+
+          LUR validation checks:
+          - Dangling references
+          - Missing types
+          - External dependencies
+          - Structural integrity
+
+          QEA validation checks:
+          - Package structure validation
+          - Class and attribute validation
+          - Association endpoint validation
+          - Referential integrity
+          - Orphaned elements
+          - Circular references
+
+          Examples:
+            lutaml uml validate model.lur
+            lutaml uml validate model.qea
+            lutaml uml validate model.qea --format json -o report.json
+          DESC
+
+          thor_class.option :format, type: :string, default: "text",
+                                     desc: "Output format (text|json)"
+          thor_class.option :output, aliases: "-o", type: :string,
+                                     desc: "Save report to file"
+          thor_class.option :strict, type: :boolean, default: false,
+                                     desc: "Exit with error if validation fails"
+          thor_class.option :show_warnings, type: :boolean, default: true,
+                                            desc: "Show warnings in output"
+          thor_class.option :verbose, type: :boolean, default: false,
+                                      desc: "Show detailed validation messages"
+        end
+
+        def run(file_path) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          unless File.exist?(file_path)
+            puts OutputFormatter.error("File not found: #{file_path}")
+            raise Thor::Error, "File not found: #{file_path}"
+          end
+
+          # Auto-detect file type
+          if file_path.end_with?(".qea")
+            validate_qea_file(file_path)
+          elsif file_path.end_with?(".lur")
+            validate_lur_file(file_path)
+          else
+            puts OutputFormatter.error(
+              "Unsupported file type. Please provide a .qea or .lur file.",
+            )
+            raise Thor::Error,
+                  "Unsupported file type. Please provide a .qea or .lur file."
+          end
+        rescue Thor::Error
+          raise
+        rescue StandardError => e
+          OutputFormatter.progress_done(success: false)
+          puts OutputFormatter.error("Validation failed: #{e.message}")
+          puts e.backtrace.first(5).join("\n") if ENV["DEBUG"]
+          raise Thor::Error, "Validation failed: #{e.message}"
+        end
+
+        private
+
+        def validate_lur_file(lur_path) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          OutputFormatter.progress("Loading package")
+          repo = Lutaml::UmlRepository::Repository.from_package(lur_path)
+          OutputFormatter.progress_done
+
+          OutputFormatter.progress("Validating repository")
+          result = repo.validate
+          OutputFormatter.progress_done
+
+          puts ""
+          if result.valid?
+            puts OutputFormatter.success("Package is valid")
+          else
+            puts OutputFormatter.warning("Package has validation issues")
+          end
+
+          display_validation_results(result)
+
+          if options[:strict] && result.errors.any?
+            raise Thor::Error, "Package validation failed"
+          end
+        end
+
+        def validate_qea_file(qea_path) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          require_relative "../../qea"
+          require_relative "../../qea/validation/formatters/text_formatter"
+          require_relative "../../qea/validation/formatters/json_formatter"
+
+          puts OutputFormatter.colorize("\n=== QEA File Validation ===\n",
+                                        :cyan)
+          puts "File: #{qea_path}"
+          puts ""
+
+          # Parse with validation
+          OutputFormatter.progress("Loading and validating QEA file")
+          result = Lutaml::Qea.parse(qea_path, validate: true)
+          OutputFormatter.progress_done
+
+          result[:document]
+          validation_result = result[:validation_result]
+
+          # Format output
+          formatter_class = case options[:format].downcase
+                            when "json"
+                              Lutaml::Qea::Validation::Formatters::JsonFormatter
+                            else
+                              Lutaml::Qea::Validation::Formatters::TextFormatter
+                            end
+
+          formatter_options = {
+            result: validation_result,
+            verbose: options[:verbose],
+          }
+          formatter_options[:color] = true if options[:format] == "text"
+
+          formatter = formatter_class.new(**formatter_options)
+          output = formatter.format
+
+          # Display or save output
+          if options[:output]
+            File.write(options[:output], output)
+            puts OutputFormatter.success(
+              "Validation report saved to: #{options[:output]}",
+            )
+          else
+            puts output
+          end
+
+          # Exit with appropriate status
+          if options[:strict] && validation_result.has_errors?
+            puts ""
+            puts OutputFormatter.error("Validation FAILED")
+            raise Thor::Error, "Validation FAILED"
+          elsif validation_result.valid?
+            puts ""
+            puts OutputFormatter.success("Validation PASSED")
+          end
+        end
+
+        def display_validation_results(result) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          if result.warnings.any?
+            puts ""
+            puts OutputFormatter.colorize("Warnings:", :yellow)
+            result.warnings.each { |w| puts "  - #{w}" }
+          end
+
+          if result.errors.any?
+            puts ""
+            puts OutputFormatter.colorize("Errors:", :red)
+            result.errors.each { |e| puts "  - #{e}" }
+          end
+
+          if result.has_external_references?
+            puts ""
+            puts OutputFormatter.colorize(
+              "External Type References (#{result.external_references.size}):",
+              :cyan,
+            )
+            puts ""
+            puts OutputFormatter.format_array_table(
+              result.external_references,
+              options: {
+                title: "Types referenced but not defined in this repository",
+                layout: false,
+              },
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/cli/uml/verify_command.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "../output_formatter"
+require_relative "../../qea/verification/document_verifier"
+
+module Lutaml
+  module Cli
+    module Uml
+      # VerifyCommand verifies XMI/QEA equivalence
+      class VerifyCommand
+        attr_reader :options
+
+        def initialize(options = {})
+          @options = options.transform_keys(&:to_sym)
+        end
+
+        def self.add_options_to(thor_class, _method_name)
+          thor_class.long_desc <<-DESC
+          Verify that QEA and XMI files contain equivalent information.
+
+          Examples:
+            lutaml uml verify model.xmi model.qea
+            lutaml uml verify model.xmi model.qea --report report.json
+          DESC
+
+          thor_class.option :report, type: :string, desc: "Save report to file"
+          thor_class.option :format, type: :string, default: "text",
+                                     desc: "Output format (text|json|yaml)"
+        end
+
+        def run(xmi_path, qea_path) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/AbcSize,Metrics/MethodLength,Metrics/PerceivedComplexity
+          unless File.exist?(xmi_path)
+            puts OutputFormatter.error("XMI file not found: #{xmi_path}")
+            raise Thor::Error, "XMI file not found: #{xmi_path}"
+          end
+
+          unless File.exist?(qea_path)
+            puts OutputFormatter.error("QEA file not found: #{qea_path}")
+            raise Thor::Error, "QEA file not found: #{qea_path}"
+          end
+
+          puts OutputFormatter.colorize(
+            "\n=== XMI/QEA Equivalence Verification ===\n", :cyan
+          )
+          puts "XMI File: #{xmi_path}"
+          puts "QEA File: #{qea_path}"
+          puts ""
+
+          OutputFormatter.progress("Verifying equivalence")
+          verifier = Lutaml::Qea::Verification::DocumentVerifier.new
+
+          begin
+            result = verifier.verify(xmi_path, qea_path)
+            OutputFormatter.progress_done
+          rescue StandardError => e
+            OutputFormatter.progress_done(success: false)
+            puts OutputFormatter.error("Verification failed: #{e.message}")
+            raise Thor::Error, "Verification failed: #{e.message}"
+          end
+
+          display_verification_result(result)
+
+          if options[:report]
+            save_verification_report(result, options[:report])
+          end
+
+          # Exit with appropriate status
+          if options[:strict] && !result.equivalent?
+            puts ""
+            puts OutputFormatter.error("Verification FAILED")
+            raise Thor::Error, "Verification FAILED"
+          elsif result.equivalent?
+            puts ""
+            puts OutputFormatter.success("Verification PASSED")
+          end
+        end
+
+        private
+
+        def display_verification_result(result)
+          puts result.summary
+
+          if result.critical_issues.any?
+            puts "\n#{OutputFormatter.colorize('Critical Issues:', :red)}"
+            result.critical_issues.each do |issue|
+              puts "  ✗ #{issue}"
+            end
+          end
+        end
+
+        def save_verification_report(result, report_path)
+          report_data = result.to_report
+          ext = File.extname(report_path).downcase
+          report_format = case ext
+                          when ".json" then :json
+                          when ".yaml", ".yml" then :yaml
+                          else :json
+                          end
+
+          File.write(report_path,
+                     OutputFormatter.format(report_data, format: report_format))
+          puts OutputFormatter.success("Report saved: #{report_path}")
+        end
+      end
+    end
+  end
+end