lutaml 0.10.4 → 0.10.6

data/TODO.cleanups/03-reduce-rspec-multiple-expectations.md

@@ -0,0 +1,54 @@
+# 03 — Reduce RSpec/MultipleExpectations (946 offenses)
+
+## Problem
+
+946 test examples have more than 1 expectation. This is the single largest rubocop offense. It makes tests brittle (failures stop at the first failed expectation, masking other issues) and harder to understand what's being verified.
+
+## Approach
+
+Split multi-expectation examples into focused single-expectation examples:
+
+```ruby
+# BEFORE:
+it "validates the widget" do
+  expect(widget.name).to eq("Test")
+  expect(widget.size).to eq(10)
+  expect(widget.active).to be true
+end
+
+# AFTER:
+it { expect(widget.name).to eq("Test") }
+it { expect(widget.size).to eq(10) }
+it { expect(widget.active).to be true }
+```
+
+For cases where multiple expectations are genuinely related (e.g., checking a hash structure), use compound matchers:
+
+```ruby
+expect(result).to include("name" => "Test", "size" => 10, "active" => true)
+```
+
+Or aggregate failures with `aggregate_failures` when the expectations are about the same concern:
+
+```ruby
+it "has correct address fields" do
+  aggregate_failures do
+    expect(address.street).to eq("Main St")
+    expect(address.city).to eq("London")
+  end
+end
+```
+
+## Priority files (highest offense density)
+
+Run `bundle exec rubocop --only RSpec/MultipleExpectations` to see the full list. Focus on:
+1. `spec/lutaml/qea/verification/comprehensive_equivalence_spec.rb`
+2. `spec/lutaml/qea/verification/equivalence_integration_spec.rb`
+3. `spec/lutaml/cli/` command specs
+4. `spec/lutaml/uml_repository/` specs
+
+## Verification
+
+- `bundle exec rubocop --only RSpec/MultipleExpectations` shows reduced count
+- `bundle exec rspec` passes
+- Reduce Max from 26 toward 5 (default)

data/TODO.cleanups/04-reduce-rspec-example-length.md

@@ -0,0 +1,45 @@
+# 04 — Reduce RSpec/ExampleLength (657 offenses)
+
+## Problem
+
+657 test examples exceed the default 5-line limit (current Max: 108). Long examples are hard to read, hide intent, and often combine setup + action + multiple assertions.
+
+## Approach
+
+Common patterns to fix:
+
+1. **Extract test data into `let`/`let!`** — Move setup out of `it` blocks:
+```ruby
+# BEFORE:
+it "parses correctly" do
+  result = described_class.parse(fixture_content)
+  expect(result.name).to eq("Test")
+end
+
+# AFTER:
+let(:result) { described_class.parse(fixture_content) }
+it { expect(result.name).to eq("Test") }
+```
+
+2. **Extract shared setup into `before` blocks** — If multiple examples repeat the same setup.
+
+3. **Use subject with one-liner syntax** — Where the subject is the tested value:
+```ruby
+subject { described_class.new(attrs) }
+it { is_expected.to be_valid }
+```
+
+4. **Extract helper methods** — Complex assertions that span many lines can become custom matchers or helper methods in `spec/support/`.
+
+## Priority
+
+Focus on the longest examples first — run `bundle exec rubocop --only RSpec/ExampleLength` and sort by severity. Files with the worst examples:
+- `spec/lutaml/qea/` verification and factory specs
+- `spec/lutaml/uml_repository/` static site specs
+- `spec/lutaml/cli/` command specs
+
+## Verification
+
+- `bundle exec rubocop --only RSpec/ExampleLength` shows reduced count
+- Reduce Max from 108 toward 10
+- `bundle exec rspec` passes

data/TODO.cleanups/05-replace-marshal-load.md

@@ -0,0 +1,37 @@
+# 05 — Replace Marshal.load with safe deserialization (4 offenses)
+
+## Problem
+
+`Marshal.load` is flagged by `Security/MarshalLoad` because deserializing untrusted data can lead to remote code execution. The gem uses it in the `.lur` package format (a ZIP file containing serialized Ruby objects).
+
+## Affected files
+
+```ruby
+# lib/lutaml/uml_repository/package_loader.rb:194
+Marshal.load(entry.get_input_stream.read)
+
+# lib/lutaml/uml_repository/package_loader.rb:210
+Marshal.load(entry.get_input_stream.read)
+
+# spec/lutaml/uml_repository/package_exporter_spec.rb:141
+expect { Marshal.load(serialized) }.not_to raise_error
+
+# spec/lutaml/uml_repository/package_exporter_spec.rb:171
+expect { Marshal.load(serialized) }.not_to raise_error
+```
+
+## Approach
+
+**Option A: Switch to JSON serialization** — Replace `Marshal.dump`/`Marshal.load` with `JSON.generate`/`JSON.parse` in `PackageExporter` and `PackageLoader`. This is safe but requires models to be JSON-serializable.
+
+**Option B: Use YAML with permitted classes** — `YAML.safe_load` with an explicit allowlist of classes. More flexible but still requires maintaining the class list.
+
+**Option C: Keep Marshal but document the trust boundary** — If `.lur` files are only ever created by the gem itself (trusted), the risk is mitigated. Add a clear comment at the load site and suppress the cop with justification.
+
+**Recommended**: Option A if feasible (cleanest), Option C as a minimal fix.
+
+## Verification
+
+- `bundle exec rubocop --only Security/MarshalLoad` shows 0 offenses
+- `.lur` package round-trip (export → load) works correctly
+- `bundle exec rspec` passes

data/TODO.cleanups/06-replace-eval-in-tests.md

@@ -0,0 +1,41 @@
+# 06 — Replace eval in tests with StringIO redirection (3 Security/Eval + 2 Style/EvalWithLocation + 2 Style/DocumentDynamicEvalDefinition)
+
+## Problem
+
+`spec/lutaml/cli/uml/search_command_spec.rb` uses `eval` to redirect `$stdout`/`$stderr` for capturing output. This triggers 7 rubocop offenses across Security and Style cops.
+
+## Affected code
+
+```ruby
+# spec/lutaml/cli/uml/search_command_spec.rb:61-65
+old_stream = eval(stream_var.to_s)
+eval("#{stream_var} = StringIO.new")
+# ...
+eval("#{stream_var} = old_stream") if defined?(old_stream) && old_stream
+```
+
+## Fix
+
+Replace with a standard output capture pattern:
+
+```ruby
+# Use RSpec's built-in output matcher:
+expect { command.run }.to output(/expected text/).to_stdout
+
+# Or use a capture helper:
+def capture_output
+  old_stdout = $stdout
+  $stdout = StringIO.new
+  yield
+  $stdout.string
+ensure
+  $stdout = old_stdout
+end
+```
+
+No `eval` needed — just use `$stdout` directly instead of dynamically resolving the variable name.
+
+## Verification
+
+- `bundle exec rubocop --only Security/Eval,Style/EvalWithLocation,Style/DocumentDynamicEvalDefinition` shows 0 offenses
+- `bundle exec rspec spec/lutaml/cli/uml/search_command_spec.rb` passes

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/exe/lutaml

@@ -5,6 +5,7 @@ require "pathname"
 bin_file = Pathname.new(__FILE__).realpath
 $:.unshift File.expand_path("../../lib", bin_file)
 
+require "lutaml"
 require "lutaml/cli"
 
 Lutaml::CLI.start(ARGV)

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,32 @@
+# 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