lutaml 0.10.4 → 0.10.5

data/TODO.cleanups/07-fix-lint-offenses.md

@@ -0,0 +1,74 @@
+# 07 — Fix Lint offenses (15 + 8 + 4 + 3 + 4 + 1 + 1 = 36 offenses)
+
+## Problem
+
+Lint cops catch real bugs and code quality issues. 36 offenses across 7 Lint cops.
+
+## Items
+
+### 1. Lint/DuplicateBranch (8 offenses)
+Identical code in different `case`/`if` branches — likely copy-paste bugs or missing differentiation.
+```
+lib/lutaml/cli/element_identifier.rb
+lib/lutaml/cli/uml/verify_command.rb
+lib/lutaml/qea/factory/base_transformer.rb
+lib/lutaml/qea/models/ea_datatype.rb
+lib/lutaml/qea/validation/validation_engine.rb
+lib/lutaml/uml_repository/queries/package_query.rb
+lib/lutaml/uml_repository/static_site/configuration.rb
+lib/lutaml/uml_repository/static_site/search_index_builder.rb
+```
+**Fix**: Merge duplicate branches or differentiate them if they should do different things.
+
+### 2. Lint/IneffectiveAccessModifier (4 offenses)
+`private`/`protected` used inside a `class << self` block — doesn't actually restrict access.
+```
+lib/lutaml/uml_repository/repository_enhanced.rb
+```
+**Fix**: Move methods outside the singleton class or use `private_class_method`.
+
+### 3. Lint/ConstantDefinitionInBlock (15 offenses)
+Constants defined inside `it`/`before` blocks leak and can cause test pollution.
+```
+spec/lutaml/model_transformations/format_registry_spec.rb
+spec/lutaml/model_transformations/parsers/base_parser_spec.rb
+spec/lutaml/model_transformations/transformation_engine_spec.rb
+spec/lutaml/model_transformations_spec.rb
+spec/lutaml/uml_repository/presenters/presenter_factory_spec.rb
+```
+**Fix**: Extract to top-level constants, use `stub_const`, or define in a shared context.
+
+### 4. Lint/EmptyConditionalBody (3 offenses)
+`if`/`unless` with empty body — likely incomplete logic.
+```
+spec/integration/qea_xmi_equivalency_spec.rb
+spec/lutaml/qea/verification/equivalence_integration_spec.rb
+```
+**Fix**: Add the missing body or refactor to use a guard clause.
+
+### 5. Lint/EmptyBlock (4 offenses)
+Empty blocks passed to methods — likely stub placeholders.
+```
+spec/lutaml/qea/integration/tagged_values_integration_spec.rb
+spec/lutaml/qea/services/database_loader_spec.rb
+spec/lutaml/uml_repository/package_exporter_spec.rb
+spec/lutaml/uml_repository/repository_spec.rb
+```
+**Fix**: Remove empty blocks or add `{ }` style comment if intentional.
+
+### 6. Lint/BinaryOperatorWithIdenticalOperands (1 offense)
+```ruby
+# spec/lutaml/qea/lookup_tables_spec.rb
+```
+**Fix**: Likely a test typo — check if both operands should be the same.
+
+### 7. Lint/MissingSuper (1 offense)
+```ruby
+# lib/lutaml/uml_repository/lazy_repository.rb
+```
+**Fix**: Add `super` call or document why it's intentionally omitted.
+
+## Verification
+
+- `bundle exec rubocop --only Lint` shows 0 offenses
+- `bundle exec rspec` passes

data/TODO.cleanups/08-reduce-memoized-helpers-and-nesting.md

@@ -0,0 +1,43 @@
+# 08 — Reduce RSpec/MultipleMemoizedHelpers (130) and RSpec/NestedGroups (29)
+
+## Problem
+
+130 examples exceed memoized helper limits (Max: 11) and 29 examples have excessive nesting (Max: 5). Both indicate test organization issues.
+
+## RSpec/MultipleMemoizedHelpers (130)
+
+Too many `let`, `let!`, `subject` declarations make test setup hard to follow. Each helper adds cognitive load.
+
+### Approach
+1. **Group-related helpers into factory methods** — Instead of 10 separate `let` declarations, use one factory:
+```ruby
+# Instead of:
+let(:name) { "Test" }
+let(:age) { 30 }
+let(:address) { Address.new(city: "London") }
+let(:person) { Person.new(name: name, age: age, address: address) }
+
+# Use:
+let(:person) { build(:person) }  # via FactoryBot or test factory
+```
+
+2. **Use `subject!` instead of separate `let` + action** — Combine setup and action.
+
+3. **Extract shared contexts** — Move common setup into `shared_context` blocks.
+
+### Priority files
+These are the worst offenders — check with `bundle exec rubocop --only RSpec/MultipleMemoizedHelpers`.
+
+## RSpec/NestedGroups (29)
+
+Deeply nested `describe`/`context` blocks (5+ levels) make tests hard to scan.
+
+### Approach
+1. **Flatten by using more descriptive top-level descriptions** — Instead of 3 levels of nesting, use a single `describe` with a descriptive name.
+2. **Extract nested contexts into separate `describe` blocks** — Move `context "when X"` / `context "and Y"` into `context "when X and Y"`.
+3. **Use shared examples** — Repeated nested structures can become shared examples.
+
+## Verification
+
+- `bundle exec rubocop --only RSpec/MultipleMemoizedHelpers,RSpec/NestedGroups` shows reduced counts
+- `bundle exec rspec` passes

data/TODO.cleanups/09-reduce-verified-doubles-and-rspec-style.md

@@ -0,0 +1,57 @@
+# 09 — Reduce RSpec/VerifiedDoubles (212) and other RSpec style offenses
+
+## Problem
+
+212 test doubles don't verify their methods exist against real classes. Other RSpec style issues total ~130 additional offenses.
+
+## RSpec/VerifiedDoubles (212 offenses)
+
+Currently disabled entirely (`Enabled: false`). Every mock/stub in the test suite uses unverified doubles:
+
+```ruby
+# CURRENT (unverified):
+let(:database) { instance_double("Database") }
+allow(database).to receive(:find_object).with(1).and_return(obj)
+
+# SHOULD BE (verified):
+let(:database) { instance_double(Lutaml::Qea::Database) }
+# Now rubocop verifies `find_object` is a real method
+```
+
+### Approach
+1. Re-enable the cop in `.rubocop_todo.yml` but with a high initial Max
+2. Fix in batches per directory:
+   - `spec/lutaml/qea/` (highest density)
+   - `spec/lutaml/uml_repository/`
+   - `spec/lutaml/cli/`
+   - rest
+3. Replace `double(...)` with `instance_double(RealClass, ...)` or `class_double(RealClass, ...)`
+4. Remove any stubbed methods that don't exist on the real class (they were wrong)
+
+### Risk
+Fixing verified doubles may expose test/implementation drift where tests mock methods that no longer exist. This is valuable — it means the tests were providing false confidence.
+
+## Other RSpec style offenses to fix in same pass
+
+| Cop | Count | Fix |
+|-----|-------|-----|
+| RSpec/ContextWording | 25 | Prefix with "when"/"with"/"without" |
+| RSpec/ExpectOutput | 90 | Use `expect { }.to output().to_stdout` |
+| RSpec/InstanceVariable | 48 | Replace `@var` with `let` (except `before(:all)` blocks) |
+| RSpec/RepeatedExample | 16 | Remove or differentiate duplicate test cases |
+| RSpec/LeakyConstantDeclaration | 15 | Use `stub_const` instead of defining constants in tests |
+| RSpec/MessageSpies | 11 | Use `have_received` instead of `receive` with `allow` |
+| RSpec/UnspecifiedException | 6 | Specify exception class in `expect { }.to raise_error(SomeError)` |
+| RSpec/SpecFilePathFormat | 6 | Rename spec files to match their described class |
+| RSpec/IndexedLet | 5 | Rename `thing1`, `thing2` to descriptive names |
+| RSpec/RepeatedExampleGroupDescription | 2 | Rename duplicate describe/context descriptions |
+| RSpec/ExpectActual | 7 | Move expectations out of `let`/`subject` |
+| RSpec/NoExpectationExample | 2 | Add expectations or use `pending` |
+| RSpec/ExpectInLet | 1 | Move expectation out of `let` |
+| RSpec/LeakyLocalVariable | 1 | Use `let` instead of local assignment |
+| RSpec/BeforeAfterAll | 1 | Evaluate if `before(:all)` can be `before(:each)` |
+
+## Verification
+
+- `bundle exec rubocop --only RSpec` shows significantly reduced count
+- `bundle exec rspec` passes

data/TODO.cleanups/10-split-large-files.md

@@ -0,0 +1,47 @@
+# 10 — Split large files into focused modules (Layout/LineLength + file organization)
+
+## Problem
+
+Several files have grown too large and do too much. The top offenders:
+
+| File | Lines | Role |
+|------|-------|------|
+| `lib/lutaml/xmi/parsers/xmi_base.rb` | 1047 | XMI parsing (13 Metrics offenses) |
+| `lib/lutaml/uml_repository/index_builder.rb` | 480 | Index building (8 Metrics offenses) |
+| `lib/lutaml/qea/database.rb` | 477 | QEA database (8 Metrics offenses) |
+| `lib/lutaml/converter/xmi_to_uml.rb` | 474 | XMI→UML conversion (8 Metrics offenses) |
+| `lib/lutaml/command_line.rb` | 272 | CLI option parsing |
+| `lib/lutaml/uml_repository/static_site/data_transformer.rb` | ~950 | Static site generation |
+
+Additionally, `Layout/LineLength` is globally disabled (80 offenses).
+
+## Approach
+
+### xmi_base.rb (1047 lines)
+Split into:
+- `xmi_base.rb` — shared module with common methods
+- `connector_parser.rb` — connector-related parsing
+- `diagram_parser.rb` — diagram-related parsing
+- `element_parser.rb` — element-related parsing
+
+### converter/xmi_to_uml.rb (474 lines)
+Split into:
+- `xmi_to_uml.rb` — main converter class
+- Per-element mapping methods extracted into separate modules or classes
+
+### database.rb (477 lines)
+Already well-organized with lazy accessors. Split:
+- `database.rb` — core + public API
+- `lookup_indexes.rb` — the `build_lookup_indexes` method and index logic
+
+### Layout/LineLength (80 offenses)
+Re-enable the cop with a reasonable Max (120) and fix the worst offenders. Long lines often indicate:
+- Deeply nested code → extract to methods
+- Complex string interpolation → use `format` or heredocs
+- Long method chains → use `tap` or break meaningfully
+
+## Verification
+
+- No file over ~300 lines in `lib/`
+- `bundle exec rubocop --only Layout/LineLength` with `Max: 120` shows 0 offenses
+- `bundle exec rspec` passes

data/bin/console

@@ -6,7 +6,6 @@ require "lutaml"
 require "lutaml/express"
 require "lutaml/uml"
 require "lutaml/xmi"
-require "lutaml/sysml"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.

data/lib/lutaml/cli/element_identifier.rb

@@ -112,12 +112,9 @@ module Lutaml
             # Lowercase start - could be attribute or diagram name
             :diagram
           end
-        when 1
-          # One separator - likely Package::Class
-          :class
-        when 2..Float::INFINITY
-          # Multiple separators - likely fully qualified class name
-          # e.g., ModelRoot::Package::Class
+        when 1..Float::INFINITY
+          # One or more separators - likely qualified class name
+          # e.g., Package::Class or ModelRoot::Package::Class
           :class
         else
           # Default

data/lib/lutaml/cli/interactive_shell/bookmark_commands.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "command_base"
+require_relative "../enhanced_formatter"
+
+module Lutaml
+  module Cli
+    class InteractiveShell
+      class BookmarkCommands < CommandBase
+        def cmd_bookmark(args)
+          return bookmark_list if args.empty?
+
+          subcommand = args[0].downcase
+
+          case subcommand
+          when "add"
+            bookmark_add(args[1])
+          when "list"
+            bookmark_list
+          when "go"
+            bookmark_go(args[1])
+          when "rm", "remove"
+            bookmark_remove(args[1])
+          else
+            bookmark_go(subcommand)
+          end
+        end
+
+        def bookmark_add(name)
+          if name.nil? || name.empty?
+            puts OutputFormatter.warning("Usage: bookmark add NAME")
+            return
+          end
+
+          target = last_results&.first || current_path
+          bookmarks[name] = target
+          puts OutputFormatter.success("Bookmark '#{name}' added: #{target}")
+        end
+
+        def bookmark_list
+          if bookmarks.empty?
+            puts "No bookmarks"
+          else
+            puts OutputFormatter.colorize("Bookmarks:", :cyan)
+            bookmarks.each do |name, target|
+              icon = config[:icons] ? "#{EnhancedFormatter::ICONS[:favorite]} " : ""
+              puts "  #{icon}#{name} → #{target}"
+            end
+          end
+        end
+
+        def bookmark_go(name)
+          unless bookmarks.key?(name)
+            puts OutputFormatter.error("Bookmark not found: #{name}")
+            return
+          end
+
+          target = bookmarks[name]
+          if repository.find_package(target)
+            push_path_history
+            self.current_path = target
+            puts "Changed to: #{target}"
+          else
+            puts OutputFormatter.warning(
+              "Bookmark target no longer exists: #{target}",
+            )
+          end
+        end
+
+        def bookmark_remove(name)
+          if bookmarks.delete(name)
+            puts OutputFormatter.success("Bookmark '#{name}' removed")
+          else
+            puts OutputFormatter.error("Bookmark not found: #{name}")
+          end
+        end
+
+        private
+
+        def push_path_history
+          return if path_history.last == current_path
+
+          path_history << current_path
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/cli/interactive_shell/command_base.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Cli
+    class InteractiveShell
+      class CommandBase
+        attr_reader :shell
+
+        def initialize(shell)
+          @shell = shell
+        end
+
+        def repository = shell.repository
+        def current_path = shell.current_path
+        def current_path=(path)
+          shell.instance_variable_set(:@current_path, path)
+        end
+        def config = shell.config
+        def bookmarks = shell.bookmarks
+        def last_results = shell.last_results
+        def last_results=(results)
+          shell.instance_variable_set(:@last_results, results)
+        end
+        def path_history = shell.path_history
+      end
+    end
+  end
+end

data/lib/lutaml/cli/interactive_shell/export_handler.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "command_base"
+
+module Lutaml
+  module Cli
+    class InteractiveShell
+      class ExportHandler < CommandBase
+        def cmd_export(args)
+          if last_results.nil? || last_results.empty?
+            puts OutputFormatter.warning("No results to export")
+            return
+          end
+
+          if args.size < 3 || args[0] != "last"
+            puts OutputFormatter.warning("Usage: export last FORMAT FILE")
+            return
+          end
+
+          format = args[1].downcase
+          file_path = args[2]
+
+          case format
+          when "csv"
+            export_csv(file_path)
+          when "json"
+            export_json(file_path)
+          when "yaml"
+            export_yaml(file_path)
+          else
+            puts OutputFormatter.error("Unsupported format: #{format}")
+          end
+        end
+
+        def export_csv(file_path)
+          require "csv"
+
+          CSV.open(file_path, "w") do |csv|
+            csv << ["Qualified Name"]
+            last_results.each do |qname|
+              csv << [qname]
+            end
+          end
+
+          puts OutputFormatter.success("Exported #{last_results.size} " \
+                                       "results to #{file_path}")
+        end
+
+        def export_json(file_path)
+          require "json"
+
+          File.write(file_path, JSON.pretty_generate(last_results))
+          puts OutputFormatter.success("Exported #{last_results.size} " \
+                                       "results to #{file_path}")
+        end
+
+        def export_yaml(file_path)
+          require "yaml"
+
+          File.write(file_path, last_results.to_yaml)
+          puts OutputFormatter.success("Exported #{last_results.size} " \
+                                       "results to #{file_path}")
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/cli/interactive_shell/help_display.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative "command_base"
+require_relative "../enhanced_formatter"
+
+module Lutaml
+  module Cli
+    class InteractiveShell
+      class HelpDisplay < CommandBase
+        def display_welcome
+          puts OutputFormatter.colorize(
+            "╔═══════════════════════════════════════╗", :cyan
+          )
+          puts OutputFormatter.colorize(
+            "║  LutaML Interactive Shell (REPL)     ║", :cyan
+          )
+          puts OutputFormatter.colorize(
+            "╚═══════════════════════════════════════╝", :cyan
+          )
+          puts ""
+          puts "Type 'help' for available commands, 'exit' to quit"
+          puts ""
+
+          stats = repository.statistics
+          puts "Repository loaded:"
+          puts "  #{stats[:total_packages]} packages, " \
+               "#{stats[:total_classes]} classes"
+          puts ""
+        end
+
+        def cmd_help(args)
+          if args.empty?
+            display_general_help
+          else
+            display_command_help(args[0])
+          end
+        end
+
+        def cmd_history(_args)
+          history = Readline::HISTORY.to_a.last(20)
+          history.each_with_index do |line, i|
+            puts "#{i + 1}. #{line}"
+          end
+        end
+
+        def cmd_clear(_args)
+          print "\e[2J\e[H"
+        end
+
+        def cmd_config(_args)
+          puts OutputFormatter.colorize("Current Configuration:", :cyan)
+          config.each do |key, value|
+            puts "  #{key}: #{value}"
+          end
+        end
+
+        def cmd_stats(_args)
+          stats = repository.statistics
+
+          if config[:icons]
+            puts EnhancedFormatter.format_stats_enhanced(stats)
+          else
+            puts OutputFormatter.format_stats(stats, detailed: false)
+          end
+        end
+
+        def display_general_help
+          puts OutputFormatter.colorize("Available Commands:", :cyan)
+          puts ""
+
+          puts OutputFormatter.colorize("Navigation:", :yellow)
+          puts "  cd PATH           Change to package path"
+          puts "  pwd               Print current path"
+          puts "  ls [PATH]         List packages"
+          puts "  tree [PATH]       Show package tree"
+          puts "  up                Go to parent package"
+          puts "  root              Go to ModelRoot"
+          puts "  back              Go to previous location"
+          puts ""
+
+          puts OutputFormatter.colorize("Query:", :yellow)
+          puts "  find CLASS        Find class (fuzzy search)"
+          puts "  show class QNAME  Show class details"
+          puts "  show package PATH Show package details"
+          puts "  show NUMBER       Show numbered result"
+          puts "  search QUERY      Full-text search"
+          puts "  ? QUERY           Alias for search"
+          puts ""
+
+          puts OutputFormatter.colorize("Bookmarks:", :yellow)
+          puts "  bookmark add NAME  Bookmark current location"
+          puts "  bookmark list      List bookmarks"
+          puts "  bookmark go NAME   Jump to bookmark"
+          puts "  bookmark rm NAME   Remove bookmark"
+          puts "  bm NAME            Quick jump"
+          puts ""
+
+          puts OutputFormatter.colorize("Utilities:", :yellow)
+          puts "  help [COMMAND]    Show help"
+          puts "  history           Show command history"
+          puts "  clear             Clear screen"
+          puts "  config            Show configuration"
+          puts "  stats             Show statistics"
+          puts "  exit, quit, q     Exit shell"
+        end
+
+        def display_command_help(command)
+          puts "Help for '#{command}' not yet implemented"
+          puts "Use 'help' for general help"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/cli/interactive_shell/navigation_commands.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "command_base"
+require_relative "../enhanced_formatter"
+
+module Lutaml
+  module Cli
+    class InteractiveShell
+      class NavigationCommands < CommandBase
+        def cmd_cd(args)
+          if args.empty?
+            puts OutputFormatter.warning("Usage: cd PATH")
+            return
+          end
+
+          path = resolve_path(args[0])
+          pkg = repository.find_package(path)
+
+          if pkg
+            push_path_history
+            self.current_path = path
+            puts "Changed to: #{path}"
+          else
+            puts OutputFormatter.error("Package not found: #{path}")
+          end
+        end
+
+        def cmd_pwd(_args)
+          puts current_path
+        end
+
+        def cmd_ls(args)
+          path = args.empty? ? current_path : resolve_path(args[0])
+          recursive = args.include?("-r") || args.include?("--recursive")
+
+          packages = repository.list_packages(path, recursive: recursive)
+
+          if packages.empty?
+            puts OutputFormatter.warning("No packages found at #{path}")
+          else
+            packages.each do |pkg|
+              icon = config[:icons] ? "#{EnhancedFormatter::ICONS[:package]} " : ""
+              puts "#{icon}#{pkg.name}"
+            end
+            puts ""
+            puts "Total: #{packages.size} package(s)"
+          end
+        end
+
+        def cmd_tree(args)
+          path = args.empty? ? current_path : resolve_path(args[0])
+
+          max_depth = nil
+          args.each_with_index do |arg, i|
+            max_depth = args[i + 1].to_i if arg == "-d" && args[i + 1]
+          end
+
+          tree_data = repository.package_tree(path, max_depth: max_depth)
+
+          unless tree_data
+            puts OutputFormatter.error("Package not found: #{path}")
+            return
+          end
+
+          if config[:icons]
+            puts EnhancedFormatter.format_tree_with_icons(tree_data, config)
+          else
+            puts OutputFormatter.format_tree(tree_data)
+          end
+        end
+
+        def cmd_up(_args)
+          if current_path == "ModelRoot"
+            puts OutputFormatter.warning("Already at root")
+            return
+          end
+
+          parts = current_path.split("::")
+          parts.pop
+          new_path = parts.empty? ? "ModelRoot" : parts.join("::")
+
+          push_path_history
+          self.current_path = new_path
+          puts "Changed to: #{current_path}"
+        end
+
+        def cmd_root(_args)
+          if current_path == "ModelRoot"
+            puts "Already at root"
+          else
+            push_path_history
+            self.current_path = "ModelRoot"
+            puts "Changed to: ModelRoot"
+          end
+        end
+
+        def cmd_back(_args)
+          if path_history.size > 1
+            path_history.pop
+            self.current_path = path_history.last
+            puts "Changed to: #{current_path}"
+          else
+            puts OutputFormatter.warning("No previous location")
+          end
+        end
+
+        def resolve_path(path)
+          return path if path.start_with?("ModelRoot")
+          return current_path if path == "."
+          return "ModelRoot" if path == "/"
+
+          if path.start_with?("../")
+            parts = current_path.split("::")
+            path.scan("../").each { parts.pop }
+            remaining = path.gsub(/^(\.\.\/)+/, "")
+            new_path = parts + remaining.split("/")
+            new_path.join("::")
+          elsif path.start_with?("./")
+            "#{current_path}::#{path[2..]}"
+          else
+            current_path == "ModelRoot" ? path : "#{current_path}::#{path}"
+          end
+        end
+
+        private
+
+        def push_path_history
+          return if path_history.last == current_path
+
+          path_history << current_path
+        end
+      end
+    end
+  end
+end