xmi 0.6.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cc49c1f04320b672d11b3bff319bc4aee6695a59b3989595af4f2e92e0a62f9
-  data.tar.gz: 8f366089bc8ad283935a06aa8b1191a54be1a26ed81014a692e59abdd26d332a
+  metadata.gz: 594be55008babe25af18895181e47ff22127d597bc56cc19c2c0b2717682e821
+  data.tar.gz: aea140572fcae2dd36e4d8b5fce6e3d8fefffe1a30fc4ce74a6ff18fd5f8f409
 SHA512:
-  metadata.gz: c90c0d2a39bc0d17452e87f8bf11ac9cb5349c1fda65b7bf65bbea2ee5e57e85f87e7b07ef3da805f75f7d12bf4eb8be2375ad777faeeee993410bdf1b4d950f
-  data.tar.gz: 7d7d33c2bde1c98942542733af1e53d2f7e66a6f57cd1421763b7d5b6e2b3a79fc9232953442fbac89135abf747cb0ba995efaaf7e40f85d3ddac23e94e1b0d4
+  metadata.gz: 12c4a3dc4575038dfde21225351477d37177cda25004cc517690b0bdbfa86aa4014ad5d2204ce10e5d0718d5d9ab4fed82cea3cefa9610c56a6bc3accd0c4142
+  data.tar.gz: b12d8eafaf2e5dcbf306769b809df0f5b80b8ca161aa4fda49e17cdeea13af5008d39b92e5f3066a73c276fe7d9a0fa3a87546fe53179cd1eeeee4f51ecbdb26

data/.rubocop_todo.yml

@@ -113,9 +113,9 @@ Lint/ConstantDefinitionInBlock:
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
-    - 'lib/tasks/benchmark_runner.rb'
-    - 'lib/tasks/performance_comparator.rb'
-    - 'lib/tasks/performance_helpers.rb'
+    - 'lib/xmi/performance/runner.rb'
+    - 'lib/xmi/performance/comparator.rb'
+    - 'lib/xmi/performance/helpers.rb'
     - 'lib/xmi/ea_root/code_generation.rb'
     - 'lib/xmi/sparx/index.rb'
     - 'lib/xmi/version_registry.rb'
@@ -131,7 +131,7 @@ Metrics/BlockLength:
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
-    - 'lib/tasks/performance_helpers.rb'
+    - 'lib/xmi/performance/helpers.rb'
     - 'lib/xmi/ea_root/code_generation.rb'
     - 'lib/xmi/sparx/index.rb'
 
@@ -144,7 +144,7 @@ Metrics/MethodLength:
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
-    - 'lib/tasks/performance_helpers.rb'
+    - 'lib/xmi/performance/helpers.rb'
     - 'lib/xmi/ea_root/code_generation.rb'
     - 'lib/xmi/sparx/index.rb'
     - 'lib/xmi/version_registry.rb'
@@ -155,7 +155,7 @@ Metrics/PerceivedComplexity:
 # AllowedIdentifiers: TLS1_1, TLS1_2, capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64
 Naming/VariableNumber:
   Exclude:
-    - 'lib/tasks/benchmark_runner.rb'
+    - 'lib/xmi/performance/runner.rb'
     - 'lib/xmi/v20110701.rb'
     - 'lib/xmi/v20131001.rb'
     - 'lib/xmi/v20161101.rb'
@@ -247,6 +247,6 @@ Style/BlockDelimiters:
 # Configuration parameters: AllowedClasses.
 Style/OneClassPerFile:
   Exclude:
-    - 'lib/tasks/benchmark_runner.rb'
+    - 'lib/xmi/performance/runner.rb'
     - 'lib/xmi.rb'
     - 'lib/xmi/namespace/dynamic.rb'

data/lib/tasks/performance.rake

@@ -1,34 +1,32 @@
 # frozen_string_literal: true
 
-require_relative "performance_comparator"
-require_relative "benchmark_runner"
+require "xmi"
 
 desc "Run performance benchmarks"
 namespace :performance do
   desc "Compare performance of current branch against base branch (default: main)"
   task :compare do
-    PerformanceComparator.new.run
+    Xmi::Performance::Comparator.new.run
   end
 
   desc "Run benchmarks on current branch only (for development)"
   task :run do
-    runner = BenchmarkRunner.new(run_time: 5)
+    runner = Xmi::Performance::Runner.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 = Xmi::Performance::Runner.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)
+    runner = Xmi::Performance::Runner.new(run_time: 5)
 
-    # Suppress pretty output, just get results
-    results = runner.send(:run_benchmarks)
+    results = runner.run_benchmarks
 
     output = results.each_with_object({}) do |(label, metrics), h|
       ips = (metrics[:lower] + metrics[:upper]) / 2.0

data/lib/xmi/performance/comparator.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Xmi
+  module Performance
+    # Orchestrates the performance comparison flow: loads the Runner
+    # into Base and Current namespaces, runs both, and reports
+    # regressions.
+    class Comparator
+      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"
+
+      def run
+        setup_environment
+        run_benchmarks_comparison
+      end
+
+      private
+
+      def setup_environment
+        Dir.chdir(REPO_ROOT)
+        Helpers.load_runner_into(Helpers::Current)
+        Helpers.load_runner_into(Helpers::Base)
+      end
+
+      def run_benchmarks_comparison
+        all_current = {}
+        all_base = {}
+
+        puts Helpers::Term.header("Performance Comparison", color: Helpers::CYAN)
+        puts
+        puts "  #{Helpers::DIM}Comparing#{Helpers::CLEAR}:"
+        puts "  #{Helpers::CYAN}  Current#{Helpers::CLEAR}: #{Helpers.current_branch}"
+        puts "  #{Helpers::CYAN}  Base#{Helpers::CLEAR}: #{DEFAULT_BASE}"
+        puts "  #{Helpers::CYAN}  Threshold#{Helpers::CLEAR}: #{(DEFAULT_THRESHOLD * 100).round(0)}% regression allowed"
+        puts
+
+        base_runner = Helpers::Base::Runner.new(
+          run_time: DEFAULT_RUN_TIME,
+        )
+        current_runner = Helpers::Current::Runner.new(
+          run_time: DEFAULT_RUN_TIME,
+        )
+
+        Helpers.run_benchmarks(
+          base_runner,
+          current_runner,
+          DEFAULT_THRESHOLD,
+          all_base,
+          all_current,
+        )
+
+        summary = Helpers.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 "  #{Helpers::RED}#{Helpers::BOLD}❌ PERFORMANCE REGRESSIONS DETECTED#{Helpers::CLEAR}"
+          puts "  #{Helpers::RED}#{summary[:regressions].length} benchmark(s) regressed beyond threshold#{Helpers::CLEAR}"
+          puts
+          exit(1)
+        else
+          puts "  #{Helpers::GREEN}#{Helpers::BOLD}✅ ALL BENCHMARKS PASSED#{Helpers::CLEAR}"
+          puts
+        end
+      end
+    end
+  end
+end

data/lib/xmi/performance/helpers.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "tmpdir"
+require "fileutils"
+
+module Xmi
+  module Performance
+    # Shared helpers for the performance benchmark rake tasks.
+    # Provides terminal formatting, git/process helpers, and the
+    # dual-namespace Runner loader used by the comparison flow.
+    module Helpers
+      # ANSI color codes for terminal output
+      CLEAR   = "\e[0m"
+      BOLD    = "\e[1m"
+      DIM     = "\e[2m"
+      CYAN    = "\e[36m"
+      GREEN   = "\e[32m"
+      YELLOW  = "\e[33m"
+      RED     = "\e[31m"
+      GRAY    = "\e[90m"
+      MAGENTA = "\e[35m"
+
+      # Terminal formatting helpers
+      module Term
+        extend self
+
+        HL = "─"
+        VL = "│"
+        TL = "┌"
+        TR = "┐"
+        BL = "└"
+        BR = "┘"
+
+        def header(title, color: Helpers::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 sep(char: HL, width: 78)
+          puts "#{DIM}#{char * width}#{CLEAR}"
+        end
+      end
+
+      # Dual-namespace containers. The Runner class is cloned into
+      # each so that Base and Current hold independent class objects
+      # (preserving the shape of the comparison API even though both
+      # currently resolve to the same benchmark code).
+      module Base
+      end
+
+      module Current
+      end
+
+      class << self
+        # Clone Xmi::Performance::Runner into the given namespace as
+        # `::Runner`. Replaces the old module_eval-of-a-top-level-file
+        # mechanism, which required require_relative and a top-level
+        # class definition incompatible with autoload.
+        def load_runner_into(namespace)
+          Xmi::Performance::Runner # force autoload
+          namespace.const_set(:Runner, Xmi::Performance::Runner.clone)
+        end
+
+        def ruby_exec(cmd, env: {})
+          Open3.capture3(env, cmd)
+        end
+
+        def current_branch
+          stdout, = ruby_exec("git rev-parse --abbrev-ref HEAD")
+          stdout.strip
+        end
+
+        def run_benchmarks(base_runner, current_runner, threshold, all_base,
+                           all_current)
+          base_results = base_runner.run_benchmarks
+          curr_results = current_runner.run_benchmarks
+
+          all_base.merge!(base_results)
+          all_current.merge!(curr_results)
+
+          comparison_rows = []
+
+          curr_results.each do |label, result|
+            base_result = base_results[label]
+            cmp = compare_metrics(label, result, base_result, threshold)
+            comparison_rows << cmp
+          end
+
+          print_comparison_table(comparison_rows, threshold)
+        end
+
+        def print_comparison_table(comparison_rows, threshold)
+          rows = comparison_rows.map do |cmp|
+            {
+              benchmark: cmp[:label],
+              base_ips: cmp[:base_ips]&.round(1),
+              curr_ips: cmp[:curr_ips]&.round(1),
+              change: cmp[:change] ? "#{(cmp[:change] * 100).round(1)}%" : "N/A",
+              status: if cmp[:base_ips].nil?
+                        "NEW"
+                      elsif cmp[:change] < -threshold
+                        "REGRESSED"
+                      else
+                        "OK"
+                      end,
+            }
+          end
+
+          return if rows.empty?
+
+          puts "  #{'Benchmark'.ljust(40)} #{'Base IPS'.rjust(12)} #{'Curr IPS'.rjust(12)} #{'Change'.rjust(10)} #{'Status'.rjust(10)}"
+          puts "  #{DIM}#{'─' * 86}#{CLEAR}"
+
+          rows.each do |row|
+            status_color = case row[:status]
+                           when "REGRESSED" then RED
+                           when "NEW" then YELLOW
+                           else GREEN
+                           end
+            row[:status] == "REGRESSED" ? RED : DIM
+
+            puts "  #{row[:benchmark].ljust(40)} #{format('%-12.1f',
+                                                          row[:base_ips] || 0)} #{format('%-12.1f',
+                                                                                         row[:curr_ips] || 0)} #{format('%-10s', row[:change]).gsub('%',
+                                                                                                                                                    '%%')} #{status_color}#{row[:status].rjust(10)}#{CLEAR}"
+          end
+
+          puts
+        end
+
+        def compare_metrics(label, curr, base, threshold)
+          unless base
+            return { label: label, base_ips: nil, curr_ips: nil, change: nil,
+                     regressed: false }
+          end
+
+          base_ips = base.fetch(:lower)
+          curr_ips = curr.fetch(:upper)
+          change = (curr_ips - base_ips) / base_ips.to_f
+
+          {
+            label: label,
+            base_ips: base_ips,
+            curr_ips: curr_ips,
+            change: change,
+            regressed: change < -threshold,
+          }
+        end
+
+        def summary_report(current_results, base_results, base, run_time, threshold)
+          summary = {
+            run_time: run_time,
+            threshold: threshold,
+            branch: current_branch,
+            base: base,
+            regressions: [],
+            new_benchmarks: [],
+          }
+
+          current_results.each do |label, metrics|
+            base_result = base_results[label]
+            cmp = compare_metrics(label, metrics, base_result, threshold)
+
+            if base_result.nil?
+              summary[:new_benchmarks] << label
+              next
+            end
+
+            next unless cmp[:regressed]
+
+            summary[:regressions] << {
+              label: label,
+              base_ips: cmp[:base_ips],
+              curr_ips: cmp[:curr_ips],
+              delta_fraction: cmp[:change],
+            }
+          end
+
+          log_regressions(summary[:regressions], threshold)
+          log_new_benchmarks(summary[:new_benchmarks])
+          summary
+        end
+
+        def log_new_benchmarks(new_benchmarks)
+          return if new_benchmarks.empty?
+
+          puts
+          puts "#{YELLOW}🆕 New benchmarks (not in base branch):#{CLEAR}"
+          new_benchmarks.each do |label|
+            puts "  • #{label}"
+          end
+        end
+
+        def log_regressions(regressions, threshold)
+          return if regressions.empty?
+
+          puts
+          puts "#{RED}⚠️  Performance Regressions Detected#{CLEAR}"
+          puts "#{RED}   (< -#{(threshold * 100).round(2)}% IPS)#{CLEAR}"
+          puts
+          regressions.each do |regression|
+            delta = regression[:delta_fraction]
+            base_ips = regression[:base_ips]
+            curr_ips = regression[:curr_ips]
+
+            delta_str = delta ? format("%+0.2f%%", delta * 100) : "N/A"
+            base_str = base_ips ? format("%.2f", base_ips) : "N/A"
+            curr_str = curr_ips ? format("%.2f", curr_ips) : "N/A"
+
+            puts "  #{BOLD}#{regression[:label]}#{CLEAR}"
+            puts "    #{GRAY}base: #{base_str} IPS#{CLEAR}"
+            puts "    #{RED}curr: #{curr_str} IPS#{CLEAR}"
+            puts "    #{RED}change: #{delta_str}#{CLEAR}"
+            puts
+          end
+        end
+      end
+    end
+  end
+end

data/lib/xmi/performance/runner.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "stringio"
+
+module Xmi
+  module Performance
+    # 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
+
+    # Runs XMI parsing benchmarks against fixture files and reports
+    # iterations-per-second with error margins.
+    class Runner
+      REPO_ROOT = File.expand_path(File.join(__dir__, "..", "..", ".."))
+
+      DEFAULT_RUN_TIME = 5
+      DEFAULT_WARMUP = 2
+
+      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
+
+      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
+
+      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|
+          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 }
+
+          $stdout = original_stdout
+        end
+
+        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
+
+        full_path = File.join(REPO_ROOT, fixture_path)
+        full_path = fixture_path unless File.exist?(full_path)
+
+        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::Root.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)
+
+        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)
+
+        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
+  end
+end

data/lib/xmi/performance.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Xmi
+  # Benchmarking and performance comparison tooling.
+  #
+  # Loaded on demand via autoload — never required at gem runtime.
+  # The rake tasks in lib/tasks/performance.rake load this module
+  # through `require "xmi"` and reference Xmi::Performance::*
+  # constants.
+  module Performance
+    autoload :Helpers, "xmi/performance/helpers"
+    autoload :Comparator, "xmi/performance/comparator"
+    autoload :Runner, "xmi/performance/runner"
+  end
+end

data/lib/xmi/uml/association_class.rb

@@ -5,7 +5,7 @@ module Xmi
     # UML `<packagedElement xmi:type="uml:AssociationClass">`. An
     # association that is also a class (UML 2.5 §11.4).
     #
-    # Phase A of TODO.next/01: subclass is a type tag on
+    # Phase A: subclass is a type tag on
     # PackagedElement. The union-bag attribute set is inherited
     # unchanged so existing consumers keep working. Phase B
     # (narrowing attrs to the subclass) is future work.