xmi 0.3.21 → 0.5.1

data/docs/versioning.md

@@ -0,0 +1,255 @@
+# XMI Version Support
+
+## Overview
+
+XMI files come in different versions with different namespace URIs. This gem handles version differences through namespace-bound registers that enable version-aware type resolution.
+
+## Version-Specific Models
+
+Some XMI elements differ between versions:
+
+| Element | XMI 2.1 | XMI 2.5.1 | XMI 2.5.2 |
+|---------|----------|------------|------------|
+| Extension | v1 | v1 (reused) | v2 |
+| Documentation | v1 | v2 | v2 (reused) |
+| Model | v1 | v1 (reused) | v1 (reused) |
+
+Where versions differ, the gem uses version-specific model classes through a fallback chain.
+
+## Fallback Chain
+
+```
+xmi_20161101
+    ↓ fallback
+xmi_20131001
+    ↓ fallback
+xmi_20110701
+    ↓ fallback
+xmi_common
+    ↓ fallback
+default
+```
+
+Types not found in a version register fall back to older versions.
+
+## Using Version-Aware Parsing
+
+### Automatic Version Detection
+
+```ruby
+require 'xmi'
+
+# Parse with automatic version detection
+doc = Xmi.parse(xml_content)
+
+# Get version information
+info = Xmi::Parsing.detect_version(xml_content)
+info[:xmi_version]  # => "20131001"
+info[:uml_version]  # => "20131001"
+info[:uris][:xmi]  # => "http://www.omg.org/spec/XMI/20131001"
+```
+
+### Explicit Version
+
+```ruby
+# Parse with explicit version
+doc = Xmi.parse_with_version(xml_content, "20131001")
+
+# Check supported versions
+Xmi::Parsing.supported_versions  # => ["20110701", "20131001", "20161101"]
+Xmi::Parsing.version_supported?("20131001")  # => true
+```
+
+### Sparx EA Files
+
+```ruby
+# For Enterprise Architect generated XMI files
+doc = Xmi::Sparx::SparxRoot.parse_xml_with_versioning(xml_content)
+```
+
+## Version Modules
+
+The gem provides version-specific modules:
+
+```ruby
+# XMI 2.1 (20110701)
+Xmi::V20110701.register  # Register for this version
+Xmi::V20110701::Extension  # Version-specific model
+Xmi::V20110701::Documentation  # Version-specific model
+
+# XMI 2.5.1 (20131001)
+Xmi::V20131001.register
+Xmi::V20131001::Documentation  # Different from V20110701
+
+# XMI 2.5.2 (20161101)
+Xmi::V20161101.register
+Xmi::V20161101::Extension  # Different from previous versions
+```
+
+## Register Fallback Resolution
+
+You can resolve types through the fallback chain:
+
+```ruby
+# Initialize versioning
+Xmi.init_versioning!
+
+# Get register for a version
+register = Xmi::V20131001.register
+
+# Resolve type with namespace awareness
+klass = register.resolve_in_namespace(
+  :extension,
+  "http://www.omg.org/spec/XMI/20131001"
+)
+# Returns Xmi::V20110701::Extension (found via fallback)
+```
+
+### Mixed namespace documents
+
+XMI documents frequently use different namespace versions for XMI, UML, UMLDI, and
+UMLDC. For example, an XMI 2.5.1 file may declare:
+
+```xml
+<xmi:XMI xmlns:xmi="http://www.omg.org/spec/XMI/20131001"
+         xmlns:uml="http://www.omg.org/spec/UML/20161101">
+```
+
+The XMI namespace is version 20131001, but the UML namespace is 20161101.
+This gem handles mixed namespace documents automatically through the
+`Xmi::VersionRegistry.detect_register` method.
+
+#### How mixed namespace detection works
+
+`detect_register` performs these steps:
+
+1. **Detect all namespace versions** from the document's namespace declarations:
+   - XMI namespace version (e.g., 20131001)
+   - UML namespace version (e.g., 20161101)
+   - UMLDI namespace version (if present)
+   - UMLDC namespace version (if present)
+
+2. **Get the primary register** for the XMI namespace version (the primary register
+   determines the overall model tree structure).
+
+3. **Extend the fallback chain** for additional namespace versions:
+   - Bind the additional namespace URIs to the primary register using proper
+     `Lutaml::Xml::Namespace` subclasses from the namespace registry.
+   - Add the additional register to the primary register's fallback chain, so
+     type resolution can find version-specific types.
+
+4. **Prevent cycles**: If the additional register's fallback chain already
+   includes the primary register, no extension is made. This prevents infinite
+   loops in type resolution.
+
+```ruby
+# Detect mixed namespaces and get configured register
+register = Xmi::VersionRegistry.detect_register(xml_content)
+# The returned register:
+# - Is bound to all namespace URIs present in the document
+# - Has an extended fallback chain for additional version registers
+# - Resolves types correctly regardless of which namespace they appear in
+
+doc = ModelClass.from_xml(xml_content, register: register)
+```
+
+#### Fallback chain extension for mixed namespaces
+
+Given a document with XMI=20131001 and UML=20161101, the register's fallback chain
+is extended as follows:
+
+```
+Primary: xmi_20131001
+  Handles: XMI 20131001, UML 20131001 namespaces
+
+  Extended fallback: xmi_20161101 (added because UML=20161101 was detected)
+    Handles: XMI 20161101, UML 20161101 namespaces
+    Own fallback: xmi_20131001 (already has XMI 20131001)
+```
+
+This allows the parser to resolve:
+
+- Types specific to the UML 20161101 version (via the extended fallback)
+- Types from the primary XMI 20131001 version (via the primary register)
+
+### Version-specific namespace binding
+
+Each version register is bound to its specific namespace URIs:
+
+```ruby
+register = Xmi::V20131001.register
+register.bound_namespace_uris
+# => ["http://www.omg.org/spec/XMI/20131001",
+#      "http://www.omg.org/spec/UML/20131001",
+#      "http://www.omg.org/spec/UML/20131001/UMLDI",
+#      "http://www.omg.org/spec/UML/20131001/UMLDC"]
+
+register.handles_namespace?("http://www.omg.org/spec/XMI/20131001")
+# => true
+
+register.handles_namespace?("http://www.omg.org/spec/XMI/20161101")
+# => false (different version)
+```
+
+## Programmatic Version Detection
+
+```ruby
+require 'xmi'
+
+# Detect version from XML content
+xml = <<~XML
+  <?xml version="1.0"?>
+  <xmi:XMI xmlns:xmi="http://www.omg.org/spec/XMI/20110701"
+           xmlns:uml="http://www.omg.org/spec/UML/20110701">
+    <xmi:Documentation>...</xmi:Documentation>
+  </xmi:XMI>
+XML
+
+info = Xmi::Parsing.detect_version(xml)
+# => { versions: { xmi: "20110701", uml: "20110701", ... },
+#      uris: { xmi: "http://...", uml: "http://...", ... },
+#      xmi_version: "20110701", uml_version: "20110701" }
+```
+
+## Error Handling
+
+Unknown versions are handled gracefully:
+
+```ruby
+# Unknown version raises ArgumentError when explicitly specified
+Xmi.parse_with_version(xml, "19990101")
+# => ArgumentError: Unknown version: 19990101
+
+# Unknown version falls back to default parsing when auto-detected
+doc = Xmi.parse(unknown_version_xml)
+# Works, but may not resolve version-specific types correctly
+```
+
+## API Reference
+
+### Module Methods
+
+| Method | Description |
+|--------|-------------|
+| `Xmi.parse(xml)` | Parse with auto-detection |
+| `Xmi.parse_with_version(xml, version)` | Parse with explicit version |
+| `Xmi.init_versioning!` | Initialize all version registers |
+| `Xmi.versioning_initialized?` | Check initialization status |
+
+### Parsing Module Methods
+
+| Method | Description |
+|--------|-------------|
+| `Xmi::Parsing.parse(xml, **options)` | Parse with options |
+| `Xmi::Parsing.parse_file(path, **options)` | Parse from file |
+| `Xmi::Parsing.detect_version(xml)` | Detect version info |
+| `Xmi::Parsing.supported_versions` | List supported versions |
+| `Xmi::Parsing.version_supported?(version)` | Check if version supported |
+
+### Version Registry Methods
+
+| Method | Description |
+|--------|-------------|
+| `Xmi::VersionRegistry.register_for_version(version)` | Get register for version |
+| `Xmi::VersionRegistry.register_for_namespace(uri)` | Get register for namespace |
+| `Xmi::VersionRegistry.detect_register(xml)` | Detect and get register |

data/lib/tasks/benchmark_runner.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+
+# Ensure lib/ is on the load path regardless of tmp location
+lib_path = File.expand_path(File.join(__dir__, "..", "..", "lib"))
+$LOAD_PATH.unshift(lib_path) unless $LOAD_PATH.include?(lib_path)
+
+require "xmi"
+
+# Pretty terminal formatting for benchmark output
+module Term
+  CLEAR   = "\e[0m"
+  BOLD    = "\e[1m"
+  DIM     = "\e[2m"
+  RED     = "\e[31m"
+  GREEN   = "\e[32m"
+  YELLOW  = "\e[33m"
+  CYAN    = "\e[36m"
+  MAGENTA = "\e[35m"
+
+  HL = "─"
+  VL = "│"
+  TL = "┌"
+  TR = "┐"
+  BL = "└"
+  BR = "┘"
+
+  def self.header(title, color: CYAN)
+    width = 78
+    line = HL * width
+    puts
+    puts "#{color}#{TL}#{line}#{TR}#{CLEAR}"
+    puts "#{color}#{VL}#{CLEAR}  #{BOLD}#{color}#{title}#{CLEAR}#{' ' * (width - title.length - 4)}#{color}#{VL}#{CLEAR}"
+    puts "#{color}#{BL}#{line}#{BR}#{CLEAR}"
+  end
+
+  def self.sep(char: HL, width: 78)
+    puts "#{DIM}#{char * width}#{CLEAR}"
+  end
+
+  def self.env_info(ruby_version, platform)
+    puts
+    puts "  #{DIM}Environment:#{CLEAR}"
+    puts "  #{VL}  Ruby #{ruby_version} on #{platform}#{' ' * (60 - ruby_version.length - platform.length)}#{VL}"
+    puts "  #{DIM}#{BL}#{HL * 76}#{BR}#{CLEAR}"
+    puts
+  end
+
+  def self.category(title, icon:, description:, failure_means:,
+compare_against: nil)
+    puts
+    puts "#{CYAN}#{VL}#{CLEAR}  #{BOLD}#{MAGENTA}#{icon} #{title}#{CLEAR}"
+    puts
+    puts "  #{DIM}#{description}#{CLEAR}"
+    puts
+
+    if compare_against
+      puts "  #{CYAN}Comparing against:#{CLEAR} #{compare_against}"
+      puts
+    end
+
+    puts "  #{YELLOW}⚠️  Failure means:#{CLEAR} #{failure_means}"
+    puts
+    sep(width: 76)
+    puts
+  end
+end
+
+class BenchmarkRunner
+  REPO_ROOT = File.expand_path(File.join(__dir__, "..", ".."))
+
+  # Benchmark configuration
+  DEFAULT_RUN_TIME = 5
+  DEFAULT_WARMUP = 2
+
+  # Category definitions with descriptions
+  CATEGORIES = {
+    xmi_parsing: {
+      name: "XMI Parsing",
+      icon: "📄",
+      description: "XMI parsing performance tests. Measures how quickly we can convert XMI files into Ruby objects.",
+      failure_means: "Slow XMI parsing impacts all downstream operations. A regression here means users will experience delays when processing XMI documents.",
+      compare_against: "Previous branch (main).",
+    },
+  }.freeze
+
+  # Test definitions
+  BENCHMARKS = {
+    xmi_parsing: [
+      { name: "XMI 2.4.2 (small)", method: :xmi_parse_242_small,
+        desc: "XMI 2.4.2 ~100KB file" },
+      { name: "XMI 2.4.2 (medium)", method: :xmi_parse_242_medium,
+        desc: "XMI 2.4.2 ~500KB file with extensions" },
+      { name: "XMI 2.4.2 (large)", method: :xmi_parse_242_large,
+        desc: "XMI 2.4.2 ~3.5MB file" },
+      { name: "XMI 2.5.1", method: :xmi_parse_251,
+        desc: "XMI 2.5.1 ~100KB file" },
+    ],
+  }.freeze
+
+  # Test data - fixture paths
+  FIXTURES = {
+    xmi_parse_242_small: "spec/fixtures/xmi-v2-4-2-default.xmi",
+    xmi_parse_242_medium: "spec/fixtures/xmi-v2-4-2-default-with-citygml.xmi",
+    xmi_parse_242_large: "spec/fixtures/full-242.xmi",
+    xmi_parse_251: "spec/fixtures/ea-xmi-2.5.1.xmi",
+  }.freeze
+
+  def initialize(run_time: nil, warmup: nil, benchmark: nil)
+    @run_time = run_time || DEFAULT_RUN_TIME
+    @warmup = warmup || DEFAULT_WARMUP
+    @benchmark = benchmark
+    @results = {}
+    @env_shown = false
+    @all_results = []
+  end
+
+  def run_benchmarks
+    Term.header("XMI Performance Benchmarks", color: Term::CYAN)
+
+    unless @env_shown
+      Term.env_info(RUBY_VERSION, RUBY_PLATFORM)
+      @env_shown = true
+    end
+
+    BENCHMARKS.each do |category, tests|
+      run_category(category, tests)
+    end
+
+    print_summary
+
+    @results
+  end
+
+  private
+
+  def run_category(category, tests)
+    config = CATEGORIES[category]
+    Term.category(
+      config[:name],
+      icon: config[:icon],
+      description: config[:description],
+      failure_means: config[:failure_means],
+      compare_against: config[:compare_against],
+    )
+
+    category_results = []
+
+    tests.each do |test|
+      # Redirect stdout during benchmark
+      original_stdout = $stdout
+      $stdout = StringIO.new
+
+      result = run_single_test(test[:method])
+      (result[:lower] + result[:upper]) / 2.0
+      category_results << { name: test[:name], result: result }
+
+      # Restore stdout
+      $stdout = original_stdout
+    end
+
+    # Print results
+    puts "  #{'Benchmark'.ljust(40)} #{'IPS'.rjust(12)} #{'Deviation'.rjust(12)}"
+    puts "  #{Term::DIM}#{Term::HL * 66}#{Term::CLEAR}"
+
+    category_results.each do |r|
+      ips = (r[:result][:lower] + r[:result][:upper]) / 2.0
+      deviation = calculate_deviation(r[:result])
+      label = "#{config[:name]}: #{r[:name]}"
+      @all_results << { label: label, ips: ips }
+      @results[label] = r[:result]
+
+      puts "  #{r[:name].ljust(40)} #{format('%.2f',
+                                             ips).rjust(12)} #{format('%.1f%%',
+                                                                      deviation).rjust(12)}"
+    end
+
+    puts
+  end
+
+  def run_single_test(method)
+    fixture_path = FIXTURES[method]
+    raise "Unknown fixture: #{method}" unless fixture_path
+
+    # Try to resolve fixture path relative to REPO_ROOT
+    full_path = File.join(REPO_ROOT, fixture_path)
+    unless File.exist?(full_path)
+      # Fallback: try current directory
+      full_path = fixture_path
+    end
+
+    xml_content = File.read(full_path)
+
+    case method
+    when :xmi_parse_242_small, :xmi_parse_242_medium, :xmi_parse_242_large, :xmi_parse_251
+      measure_time { Xmi::Sparx::SparxRoot.parse_xml(xml_content) }
+    else
+      raise "Unknown benchmark: #{method}"
+    end
+  end
+
+  def measure(&)
+    job = Benchmark::IPS::Job.new
+    job.config(time: @run_time, warmup: @warmup)
+    job.report("test", &)
+    job.run
+
+    entry = job.full_report.entries.first
+    samples = entry.stats.samples
+
+    return { lower: 0, upper: 0 } if samples.empty?
+
+    mean = samples.sum.to_f / samples.size
+    variance = samples.sum { |x| (x - mean)**2 } / (samples.size - 1)
+    std_dev = Math.sqrt(variance)
+    error_margin = std_dev / mean
+    error_pct = error_margin.round(4)
+
+    { lower: mean.round(4) * (1 - error_pct),
+      upper: mean.round(4) * (1 + error_pct) }
+  end
+
+  def measure_time
+    times = []
+    iterations = 5
+
+    iterations.times do
+      start_t = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      yield
+      finish_t = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      times << (finish_t - start_t)
+    end
+
+    mean = times.sum / times.size
+    variance = times.sum { |t| (t - mean)**2 } / (times.size - 1)
+    std_dev = Math.sqrt(variance)
+
+    # Use conservative estimates for time-based measurement
+    lower_time = [mean - std_dev, mean * 0.5].max
+    lower_ips = (1.0 / (lower_time * 1.5)).round(4)
+    upper_ips = (1.0 / mean).round(4)
+
+    # For fast operations, estimate more conservatively
+    if mean < 0.001
+      upper_ips = (1.0 / mean).round(4)
+      lower_ips = (upper_ips * 0.8).round(4)
+    end
+
+    { lower: lower_ips, upper: upper_ips }
+  end
+
+  def calculate_deviation(metrics)
+    return 0 if metrics[:upper].zero?
+
+    ((metrics[:upper] - metrics[:lower]) / metrics[:upper] * 100).round(1)
+  end
+
+  def print_summary
+    puts
+    Term.sep(width: 78)
+    puts
+    puts "  #{Term::BOLD}#{Term::MAGENTA}SUMMARY#{Term::CLEAR}"
+    puts
+
+    @all_results.each do |r|
+      puts "  #{r[:label].ljust(60)} #{format('%.2f', r[:ips]).rjust(10)} IPS"
+    end
+
+    puts
+    puts "  #{Term::DIM}#{@all_results.length} benchmarks completed#{Term::CLEAR}"
+    puts
+  end
+end

data/lib/tasks/performance.rake

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "performance_comparator"
+require_relative "benchmark_runner"
+
+desc "Run performance benchmarks"
+namespace :performance do
+  desc "Compare performance of current branch against base branch (default: main)"
+  task :compare do
+    PerformanceComparator.new.run
+  end
+
+  desc "Run benchmarks on current branch only (for development)"
+  task :run do
+    runner = BenchmarkRunner.new(run_time: 5)
+    runner.run_benchmarks
+  end
+
+  desc "Quick benchmark run (faster, less accurate)"
+  task :quick do
+    runner = BenchmarkRunner.new(run_time: 2, warmup: 1)
+    runner.run_benchmarks
+  end
+
+  desc "Run benchmarks and output as JSON"
+  task :json do
+    require "json"
+    runner = BenchmarkRunner.new(run_time: 5)
+
+    # Suppress pretty output, just get results
+    results = runner.send(:run_benchmarks)
+
+    output = results.each_with_object({}) do |(label, metrics), h|
+      ips = (metrics[:lower] + metrics[:upper]) / 2.0
+      deviation = ((metrics[:upper] - metrics[:lower]) / metrics[:upper] * 100).round(1)
+      h[label] = {
+        ips: ips.round(2),
+        lower: metrics[:lower].round(2),
+        upper: metrics[:upper].round(2),
+        deviation: deviation,
+      }
+    end
+
+    puts JSON.pretty_generate(output)
+  end
+end

data/lib/tasks/performance_comparator.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "performance_helpers"
+
+class PerformanceComparator
+  REPO_ROOT = File.expand_path(File.join(__dir__, "..", ".."))
+  DEFAULT_RUN_TIME = 10
+  DEFAULT_THRESHOLD = 0.10 # 10% (more lenient for complex operations)
+  DEFAULT_BASE = "main"
+  TMP_PERF_DIR = File.join(REPO_ROOT, "tmp", "performance")
+  BENCH_SCRIPT = File.join(TMP_PERF_DIR, "benchmark_runner.rb")
+
+  def run
+    setup_environment
+    run_benchmarks_comparison
+  ensure
+    cleanup
+  end
+
+  private
+
+  def setup_environment
+    Dir.chdir(REPO_ROOT)
+    FileUtils.mkdir_p(TMP_PERF_DIR)
+    FileUtils.cp(File.join(REPO_ROOT, "lib", "tasks", "benchmark_runner.rb"),
+                 BENCH_SCRIPT)
+
+    PerformanceHelpers.load_into_namespace(PerformanceHelpers::Current,
+                                           BENCH_SCRIPT)
+    PerformanceHelpers.clone_base_repo(DEFAULT_BASE, TMP_PERF_DIR, BENCH_SCRIPT)
+  end
+
+  def run_benchmarks_comparison
+    all_current = {}
+    all_base = {}
+
+    puts PerformanceHelpers::Term.header("Performance Comparison", color: PerformanceHelpers::CYAN)
+    puts
+    puts "  #{PerformanceHelpers::DIM}Comparing#{PerformanceHelpers::CLEAR}:"
+    puts "  #{PerformanceHelpers::CYAN}  Current#{PerformanceHelpers::CLEAR}: #{PerformanceHelpers.current_branch}"
+    puts "  #{PerformanceHelpers::CYAN}  Base#{PerformanceHelpers::CLEAR}: #{DEFAULT_BASE}"
+    puts "  #{PerformanceHelpers::CYAN}  Threshold#{PerformanceHelpers::CLEAR}: #{(DEFAULT_THRESHOLD * 100).round(0)}% regression allowed"
+    puts
+
+    # Run all benchmarks
+    base_runner = PerformanceHelpers::Base::BenchmarkRunner.new(
+      run_time: DEFAULT_RUN_TIME,
+    )
+    current_runner = PerformanceHelpers::Current::BenchmarkRunner.new(
+      run_time: DEFAULT_RUN_TIME,
+    )
+
+    PerformanceHelpers.run_benchmarks(
+      base_runner,
+      current_runner,
+      DEFAULT_THRESHOLD,
+      all_base,
+      all_current,
+    )
+
+    summary = PerformanceHelpers.summary_report(
+      all_current,
+      all_base,
+      DEFAULT_BASE,
+      DEFAULT_RUN_TIME,
+      DEFAULT_THRESHOLD,
+    )
+
+    handle_results(summary)
+  end
+
+  def handle_results(summary)
+    puts
+    if summary[:regressions].any?
+      puts "  #{PerformanceHelpers::RED}#{PerformanceHelpers::BOLD}❌ PERFORMANCE REGRESSIONS DETECTED#{PerformanceHelpers::CLEAR}"
+      puts "  #{PerformanceHelpers::RED}#{summary[:regressions].length} benchmark(s) regressed beyond threshold#{PerformanceHelpers::CLEAR}"
+      puts
+      exit(1)
+    else
+      puts "  #{PerformanceHelpers::GREEN}#{PerformanceHelpers::BOLD}✅ ALL BENCHMARKS PASSED#{PerformanceHelpers::CLEAR}"
+      puts
+    end
+  end
+
+  def cleanup
+    FileUtils.rm_rf(TMP_PERF_DIR)
+  end
+end