xmi 0.5.5 → 0.5.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a7c79e8d907feee2589c9cd13f534297ffd3869b15bf1c05db190b59903fdaa
-  data.tar.gz: f46a5b384fe0f8da80d075766fe226d8519c3b0a72739b66220c606012f098ab
+  metadata.gz: 62e6b5232df619d790a5ca7b69454d3ed6f2762bb457808436be572162867f16
+  data.tar.gz: 4adbc6c45fd9e75a2fb6612f60cb35ef47a91afe44cca8c366f8c9b17237aeab
 SHA512:
-  metadata.gz: 7e54e2c55800f18215428d8001502c9476d1b63a9dd9db3a164de3e0eae569a0fc405b237adc07e2a2e6fbd789e001a2a57df26cc276b3c9ea8ffccc349159a4
-  data.tar.gz: 12c434257662c1a5291f915e97b197497a1153676c57b997e0392b00fc90c08ba712781f859ccdaf4b76f25b17ec3c6277480d9f6a2f5c1b763fe92d24f7341c
+  metadata.gz: fad7e8f844a110c38395e3d6b90f5506832cf4d971830b3dee23294d7268c6183b5a07ffafaa0832aba65b13ae1a2ad7dae7176b93d333c1607ef5607079f7af
+  data.tar.gz: e81076d61606ae1742f08fffa61aa7b0efd999c29dcbffd1c80ee5a34b81adaeb79bb988021f33a07cb51c8c16d023a09cdf5b884905dfb80b4070634731dbdd

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-04-21 01:02:50 UTC using RuboCop version 1.86.1.
+# on 2026-04-22 09:21:04 UTC using RuboCop version 1.86.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -11,15 +11,7 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'xmi.gemspec'
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: empty_lines, no_empty_lines
-Layout/EmptyLinesAroundBlockBody:
-  Exclude:
-    - 'spec/xmi/ea_root/extension_loading_spec.rb'
-
-# Offense count: 76
+# Offense count: 77
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
@@ -60,7 +52,7 @@ Metrics/CyclomaticComplexity:
     - 'lib/xmi/ea_root/code_generation.rb'
     - 'lib/xmi/sparx/index.rb'
 
-# Offense count: 28
+# Offense count: 30
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 55
@@ -141,12 +133,19 @@ RSpec/MultipleMemoizedHelpers:
 RSpec/NestedGroups:
   Max: 4
 
-# Offense count: 1
+# Offense count: 8
 # Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
 # SupportedInflectors: default, active_support
 RSpec/SpecFilePathFormat:
   Exclude:
     - 'spec/xmi/ea_root/extension_loading_spec.rb'
+    - 'spec/xmi/sparx/sparx_root_citygml_rel_ns_spec.rb'
+    - 'spec/xmi/sparx/sparx_root_citygml_spec.rb'
+    - 'spec/xmi/sparx/sparx_root_eauml_spec.rb'
+    - 'spec/xmi/sparx/sparx_root_gml_spec.rb'
+    - 'spec/xmi/sparx/sparx_root_mdg_spec.rb'
+    - 'spec/xmi/sparx/sparx_root_xmi2013_uml2013_spec.rb'
+    - 'spec/xmi/sparx/sparx_root_xmi_parsing_spec.rb'
 
 # Offense count: 4
 # Configuration parameters: AllowedClasses.

data/CLAUDE.md

@@ -0,0 +1,166 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build, Test, and Development Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rake spec
+bundle exec rspec
+
+# Run a single test file
+bundle exec rspec spec/xmi/sparx/sparx_root_xmi2013_uml2013_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/xmi/sparx/sparx_root_xmi2013_uml2016_spec.rb:610
+
+# Run linter with auto-correct
+bundle exec rubocop -A --auto-gen-config
+
+# Run both tests and linting (default rake task)
+bundle exec rake
+
+# Interactive console for experimentation
+bin/console
+```
+
+## Architecture Overview
+
+This gem converts XMI (XML Metadata Interchange) files into Ruby objects, specifically designed for Enterprise Architect generated XMI files.
+
+### Core Dependencies
+
+- **lutaml-model**: All serializable models inherit from `Lutaml::Model::Serializable`
+- **nokogiri**: XML parsing backend
+
+### Main Entry Point
+
+`Xmi::Sparx::Root.parse_xml(xml_content)` is the primary method to parse XMI files. It performs preprocessing before parsing:
+
+1. `fix_encoding` - Fixes invalid UTF-8 byte sequences in the XML content
+2. `normalize_omg_namespace_versions` - Normalizes OMG namespace versions (XMI, UML) to canonical 20131001
+3. `resolve_relative_namespaces` - Replaces relative `xmlns` values with `targetNamespace` values
+4. `rename_ea_xmlns_attribute` - Renames `xmlns` attribute to `altered_xmlns` on EA-specific elements (see below)
+
+### OMG Namespace Version Normalization
+
+OMG publishes XMI and UML specifications with dated namespace URIs (e.g., `http://www.omg.org/spec/XMI/20110701`, `20131001`, `20161101`). This library normalizes all versions to `20131001` during parsing, allowing a single set of model classes to handle all versions.
+
+### Enterprise Architect's Misuse of the `xmlns` Attribute
+
+**This is a critical quirk to understand when working with EA-generated XMI.**
+
+In standard XML, `xmlns` is a reserved attribute for namespace declarations. However, Enterprise Architect incorrectly uses `xmlns` as a **regular data attribute** on certain stereotype elements (e.g., `GML:ApplicationSchema`, `CityGML:ApplicationSchema`), storing arbitrary URI values unrelated to namespace declarations.
+
+This violates XML conventions and creates parsing conflicts—XML libraries treat `xmlns` as reserved. The library works around this by renaming `xmlns` to `altered_xmlns` before parsing:
+
+```xml
+<!-- EA-generated -->
+<GML:ApplicationSchema xmlns="http://some-value" ...>
+
+<!-- After preprocessing -->
+<GML:ApplicationSchema altered_xmlns="http://some-value" ...>
+```
+
+Model classes define `altered_xmlns` attributes to receive these values:
+
+```ruby
+class ApplicationSchema < Lutaml::Model::Serializable
+  attribute :altered_xmlns, :string  # renamed from xmlns
+end
+```
+
+### Namespace Architecture
+
+**All XMI/UML namespace versions are normalized to 20131001 before parsing** (see `Root.replace_xmlns`).
+
+Namespace classes are defined in:
+- `lib/xmi/namespace/omg.rb` - OMG namespaces (XMI, UML, UmlDi, UmlDc)
+- `lib/xmi/namespace/sparx.rb` - Sparx-specific profiles (SysPhS, GML, EaUml, CustomProfile, CityGML)
+
+Use version-agnostic alias classes that inherit from 20131001 versions:
+```ruby
+::Xmi::Namespace::Omg::Xmi   # => inherits from Xmi20131001
+::Xmi::Namespace::Omg::Uml   # => inherits from Uml20131001
+```
+
+### Custom Types with XML Namespace
+
+Custom types in `lib/xmi/type.rb` declare their XML namespace using the `xml do ... end` block:
+
+```ruby
+class XmiId < Lutaml::Model::Type::String
+  xml do
+    namespace ::Xmi::Namespace::Omg::Xmi
+  end
+end
+```
+
+### Model Definition Pattern
+
+Models use lutaml-model syntax with explicit namespace declarations:
+```ruby
+class MyModel < Lutaml::Model::Serializable
+  attribute :id, ::Xmi::Type::XmiId
+
+  xml do
+    root "Model"
+    namespace ::Xmi::Namespace::Omg::Uml
+    namespace_scope [::Xmi::Namespace::Omg::Xmi, ::Xmi::Namespace::Omg::Uml]
+
+    # Attributes with XMI namespace require explicit declaration
+    map_attribute "id", to: :id,
+                       namespace: "http://www.omg.org/spec/XMI/20131001",
+                       prefix: "xmi"
+  end
+end
+```
+
+### Dynamic Extension Loading
+
+`Xmi::EaRoot.load_extension(xml_path)` dynamically generates Ruby classes from EA MDG extension XML files. This creates stereotype classes under `Xmi::EaRoot::{ModuleName}::{ClassName}` and updates `Root` mappings.
+
+Extensions use `NamespaceRegistry` to look up or create namespace classes dynamically:
+- Existing namespace URIs resolve to predefined classes
+- New URIs create dynamic classes under `Xmi::Namespace::Dynamic::{ModuleName}`
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `lib/xmi.rb` | Main entry point, loads dependencies and configures XML adapter |
+| `lib/xmi/sparx.rb` | Module with autoload declarations for Sparx components |
+| `lib/xmi/sparx/root.rb` | Main `Root` class with parsing and namespace normalization |
+| `lib/xmi/root.rb` | Base `Root` class with common XMI attributes |
+| `lib/xmi/uml.rb` | UML model classes (UmlModel, PackagedElement, etc.) |
+| `lib/xmi/ea_root.rb` | Dynamic extension loading from MDG XML |
+| `lib/xmi/type.rb` | Custom types with namespace declarations (XmiId, XmiType, etc.) |
+| `lib/xmi/namespace/omg.rb` | OMG namespace classes (XMI, UML, UmlDi, UmlDc) |
+| `lib/xmi/namespace/sparx.rb` | Sparx-specific profile namespaces |
+| `lib/xmi/namespace_registry.rb` | URI-to-class mapping for namespace lookup |
+
+### Collection Value Maps
+
+When mapping collection elements, use the standard `VALUE_MAP` pattern to handle nil/empty values:
+
+```ruby
+map_element "Element", to: :elements,
+              value_map: {
+                from: { nil: :empty, empty: :empty, omitted: :empty },
+                to: { nil: :empty, empty: :empty, omitted: :empty }
+              }
+```
+
+A shared constant is available at `Xmi::Sparx::VALUE_MAP`.
+
+## Known Issues
+
+One serialization test fails due to a lutaml-model bug where `to_xml` does not respect namespace declarations on custom types. See `LUTAML_MODEL_BUG_REPORT.md` for details. Parsing works correctly; only serialization is affected.
+
+## Limitations
+
+This gem is designed for Enterprise Architect generated XMI files and may not work with XMI from other tools. Some EA-specific elements (e.g., `GML:ApplicationSchema`) use `xmlns` as an attribute, which is renamed to `altered_xmlns` during preprocessing to avoid conflicts with Lutaml::Model internals.

data/README.adoc

@@ -157,7 +157,7 @@ classes.
 
 === Namespace Normalization
 
-The normalization is performed by [`SparxRoot.replace_xmlns`](lib/xmi/sparx.rb:1158) which rewrites
+The normalization is performed by `Xmi::ParserPipeline` which rewrites
 namespace URIs in the input XML:
 
 .Example of namespace normalization
@@ -180,7 +180,7 @@ namespace URIs in the input XML:
 
 === Namespace Classes
 
-Namespace classes are defined in [`lib/xmi/namespace/omg.rb`](lib/xmi/namespace/omg.rb:1):
+Namespace classes are defined in `lib/xmi/namespace/omg.rb`:
 
 * **Version-specific classes**: `Xmi20110701`, `Uml20131001`, etc.
 * **Version-agnostic aliases**: `Xmi`, `Uml`, `UmlDi`, `UmlDc`
@@ -277,7 +277,7 @@ namespace prefixes will parse as `nil`.
 
 === Sparx Systems Namespaces
 
-Sparx-specific namespaces are defined in [`lib/xmi/namespace/sparx.rb`](lib/xmi/namespace/sparx.rb:1):
+Sparx-specific namespaces are defined in `lib/xmi/namespace/sparx.rb`:
 
 * **SysPhS** - System Physical Systems profile
 * **GML** - Geography Markup Language profile
@@ -301,7 +301,7 @@ end
 
 === Extension Namespaces
 
-Dynamically loaded extensions (via [`EaRoot.load_extension`](lib/xmi/ea_root.rb:54)) also use
+Dynamically loaded extensions (via `EaRoot.load_extension`) also use
 namespace-qualified mappings:
 
 .Extension with namespace mapping
@@ -384,17 +384,14 @@ The old API used `SparxRoot.parse_xml` with automatic namespace normalization:
 [source,ruby]
 ----
 # Old API (still works, but version-aware API is recommended)
-doc = Xmi::Sparx::SparxRoot.parse_xml(xml_content)
+doc = Xmi::Sparx::Root.parse_xml(xml_content)
 ----
 
 The new version-aware API:
 
 [source,ruby]
 ----
-# New API - explicit about version handling
-doc = Xmi::Sparx::SparxRoot.parse_xml_with_versioning(xml_content)
-
-# Or use the module-level API
+# New API - module-level convenience method
 doc = Xmi.parse(xml_content)
 ----
 
@@ -465,13 +462,13 @@ define an `altered_xmlns` attribute to receive this value.
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to https://rubygems.org[rubygems.org].
 
 
 == Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/xmi. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/xmi/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/lutaml/xmi. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the https://github.com/lutaml/xmi/blob/master/CODE_OF_CONDUCT.md[code of conduct].
 
 == Code of Conduct
 
-Everyone interacting in the Xmi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/xmi/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Xmi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the https://github.com/lutaml/xmi/blob/master/CODE_OF_CONDUCT.md[code of conduct].

data/TODO.perf/01-eliminate-duplicate-nokogiri-parse.md

@@ -0,0 +1,33 @@
+# 01: Eliminate Duplicate Nokogiri Parse
+
+## Impact: HIGH (~30-50% parse time for large files)
+
+## Problem
+
+`ParserPipeline` parses XML twice:
+1. `NamespaceDetector.detect_versions` → `Nokogiri::XML(xml_content)` + `collect_namespaces` — parses entire doc just to read root namespace URIs
+2. `from_xml` → adapter.parse(xml_content) — parses again via lutaml-model
+
+For the 3.5MB large fixture, this is the dominant cost.
+
+## Fix
+
+Extract namespace URIs from the first ~4KB of the XML string using regex, avoiding Nokogiri entirely for version detection.
+
+```ruby
+# Instead of:
+doc = Nokogiri::XML(xml_content)
+doc.collect_namespaces
+
+# Use:
+NS_REGEX = /xmlns:?(\\w*)=["']([^"']+)["']/
+xml_content[0, 4096].scan(NS_REGEX).to_h { |prefix, uri| [prefix, uri] }
+```
+
+The namespace declarations are always on or near the root element, so scanning the first 4KB is sufficient.
+
+## Files
+
+- `lib/xmi/namespace_detector.rb` — replace `extract_namespace_uris` Nokogiri parse with regex
+- `lib/xmi/namespace_detector.rb` — verify `detect_versions` still works
+- `spec/xmi/parser_pipeline_spec.rb` — verify tests pass

data/TODO.perf/02-read-only-fast-mode.md

@@ -0,0 +1,38 @@
+# 02: Read-Only Fast Mode (Skip Namespace Declaration Plan)
+
+## Impact: HIGH (eliminates full tree walk before mapping starts)
+
+## Problem
+
+In lutaml-model's `ModelTransform#data_to_model` (lines 71-76), `build_input_declaration_plan` calls `collect_element_namespaces` which recursively walks **every element** in the parsed document — solely for round-trip namespace fidelity (preserving xmlns declarations for `to_xml`).
+
+Most XMI consumers only parse (read) and never call `to_xml`. This full tree walk is wasted work.
+
+## Fix
+
+### In lutaml-model
+
+Add a `parse_only: true` option to `from_xml` that skips namespace declaration plan collection:
+
+```ruby
+# model_transform.rb line 71
+unless options.key?(:lutaml_parent) || options[:parse_only]
+  input_declaration_plan = build_input_declaration_plan(root_element)
+  # ...
+end
+```
+
+### In xmi gem
+
+Pass `parse_only: true` in `ParserPipeline::ParseXml` step:
+
+```ruby
+model_class.from_xml(ctx[:xml], register: register, parse_only: true)
+```
+
+If the user later calls `to_xml`, it works but without preserved input namespace declarations (acceptable for read-only use). If they need full round-trip, they opt out of `parse_only`.
+
+## Files
+
+- `lutaml-model/lib/lutaml/xml/model_transform.rb` — gate `build_input_declaration_plan` behind `parse_only` option
+- `lib/xmi/parser_pipeline.rb` — pass `parse_only: true` in ParseXml step

data/TODO.perf/03-register-fallback-idempotency.md

@@ -0,0 +1,20 @@
+# 03: Register Fallback Idempotency Guard
+
+## Impact: MEDIUM (prevents cache invalidation on every parse)
+
+## Problem
+
+`extend_fallback_for_mixed_namespaces` is called on every `parse_xml` for mixed-namespace documents. It calls `primary_register.add_fallback(reg.id)` which invalidates internal caches even when the fallback was already added on a previous parse.
+
+## Fix
+
+Add a guard before calling `add_fallback`:
+
+```ruby
+next if primary_register.fallback.include?(reg.id)
+primary_register.add_fallback(reg.id)
+```
+
+## Files
+
+- `lib/xmi/namespace_detector.rb` or `lib/xmi/version_registry.rb` — find where `extend_fallback_for_mixed_namespaces` is called and add the guard

data/TODO.perf/04-pipeline-hash-mutation.md

@@ -0,0 +1,31 @@
+# 04: Pipeline Hash Mutation
+
+## Impact: LOW (saves 4 intermediate Hash allocations per parse)
+
+## Problem
+
+Each pipeline step returns `ctx.merge(key: value)` creating intermediate Hash objects.
+
+## Fix
+
+Use `ctx[:key] = value` mutation instead:
+
+```ruby
+# Before
+def self.call(ctx)
+  xml = ctx[:xml]
+  # ...process...
+  ctx.merge(xml: fixed_xml)
+
+# After
+def self.call(ctx)
+  xml = ctx[:xml]
+  # ...process...
+  ctx[:xml] = fixed_xml
+  ctx
+end
+```
+
+## Files
+
+- `lib/xmi/parser_pipeline.rb` — all 4 step modules

data/TODO.perf/05-ea-root-single-parse.md

@@ -0,0 +1,29 @@
+# 05: EaRoot Single Parse for Extension Loading
+
+## Impact: LOW (only affects load_extension, not parse_xml hot path)
+
+## Problem
+
+`EaRoot.load_extension(xml_path)` reads and parses the XML file twice:
+1. `derive_module_name` in `ea_root.rb:54-56` — `Nokogiri::XML(File.read(xml_path))`
+2. `build_extension` in `code_generation.rb:8` — `Nokogiri::XML(File.read(xml_path))`
+
+## Fix
+
+Parse once in `load_extension`, pass the Nokogiri doc to both:
+
+```ruby
+def load_extension(xml_path)
+  xmi_doc = Nokogiri::XML(File.read(xml_path))
+  extension_id = get_module_name(xmi_doc)
+  # ...guard...
+  build_extension_from_doc(xmi_doc)
+  update_mappings(extension_id)
+  loaded_extensions[extension_id] = xml_path
+end
+```
+
+## Files
+
+- `lib/xmi/ea_root.rb` — parse once, pass doc
+- `lib/xmi/ea_root/code_generation.rb` — accept doc parameter instead of file path

data/docs/migration.md

@@ -12,7 +12,7 @@ The old API used `SparxRoot.parse_xml` with automatic namespace normalization:
 require 'xmi'
 
 # Old approach - normalizes all namespaces to 20131001
-doc = Xmi::Sparx::SparxRoot.parse_xml(xml_content)
+doc = Xmi::Sparx::Root.parse_xml(xml_content)
 ```
 
 This approach:
@@ -31,7 +31,7 @@ require 'xmi'
 doc = Xmi.parse(xml_content)
 
 # Or for Sparx EA files
-doc = Xmi::Sparx::SparxRoot.parse_xml_with_versioning(xml_content)
+doc = Xmi::Sparx::Root.parse_xml_with_versioning(xml_content)
 ```
 
 This approach:
@@ -45,10 +45,10 @@ This approach:
 
 ```ruby
 # Before
-doc = Xmi::Sparx::SparxRoot.parse_xml(xml_content)
+doc = Xmi::Sparx::Root.parse_xml(xml_content)
 
 # After
-doc = Xmi::Sparx::SparxRoot.parse_xml_with_versioning(xml_content)
+doc = Xmi::Sparx::Root.parse_xml_with_versioning(xml_content)
 
 # Or
 doc = Xmi.parse(xml_content)
@@ -86,7 +86,7 @@ doc = Xmi.parse_with_version(xml_content, "20131001")
 
 | Use Case | Recommended API |
 |----------|----------------|
-| Sparx EA files | `Xmi::Sparx::SparxRoot.parse_xml_with_versioning` |
+| Sparx EA files | `Xmi::Sparx::Root.parse_xml_with_versioning` |
 | General XMI files | `Xmi.parse` |
 | Version detection | `Xmi::Parsing.detect_version` |
 | Known version | `Xmi.parse_with_version(xml, version)` |
@@ -97,7 +97,7 @@ The old `parse_xml` method still works but normalizes namespaces:
 
 ```ruby
 # Old API - still supported
-doc = Xmi::Sparx::SparxRoot.parse_xml(xml_content)
+doc = Xmi::Sparx::Root.parse_xml(xml_content)
 
 # This internally normalizes to 20131001 namespace
 ```

data/docs/versioning.md

@@ -64,7 +64,7 @@ Xmi::Parsing.version_supported?("20131001")  # => true
 
 ```ruby
 # For Enterprise Architect generated XMI files
-doc = Xmi::Sparx::SparxRoot.parse_xml_with_versioning(xml_content)
+doc = Xmi::Sparx::Root.parse_xml_with_versioning(xml_content)
 ```
 
 ## Version Modules

data/lib/tasks/benchmark_runner.rb

@@ -194,7 +194,7 @@ class BenchmarkRunner
 
     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) }
+      measure_time { Xmi::Sparx::Root.parse_xml(xml_content) }
     else
       raise "Unknown benchmark: #{method}"
     end

data/lib/xmi/ea_root/code_generation.rb

@@ -4,8 +4,7 @@ module Xmi
   class EaRoot
     module CodeGeneration
       # Build extension classes directly via Class.new + const_set.
-      def build_extension(xml_path)
-        xmi_doc = Nokogiri::XML(File.read(xml_path))
+      def build_extension(xmi_doc)
         @module_name = get_module_name(xmi_doc)
         @def_namespace = get_namespace_from_definition(xmi_doc)
 

data/lib/xmi/ea_root/extension_lifecycle.rb

@@ -12,7 +12,7 @@ module Xmi
       private
 
       def inject_model_attributes(new_klasses, module_name)
-        sparx_root = Xmi::Sparx::SparxRoot
+        sparx_root = Xmi::Sparx::Root
         new_klasses.each do |klass_name|
           method_name = Lutaml::Model::Utils.snake_case(klass_name)
           full_klass = EaRoot.const_get(module_name).const_get(klass_name)
@@ -32,7 +32,7 @@ module Xmi
 
         return if map_entries.empty?
 
-        Xmi::Sparx::SparxRoot.class_eval do
+        Xmi::Sparx::Root.class_eval do
           xml do
             map_entries.each do |element_name, method_sym|
               map_element element_name, to: method_sym,

data/lib/xmi/ea_root.rb

@@ -18,7 +18,8 @@ module Xmi
 
     class << self
       def load_extension(xml_path)
-        extension_id = derive_module_name(xml_path)
+        xmi_doc = Nokogiri::XML(File.read(xml_path))
+        extension_id = get_module_name(xmi_doc)
 
         if loaded_extensions.key?(extension_id)
           raise ArgumentError,
@@ -27,7 +28,7 @@ module Xmi
                 "Call unload_extension('#{extension_id}') first if you want to reload it."
         end
 
-        build_extension(xml_path)
+        build_extension(xmi_doc)
         update_mappings(extension_id)
         loaded_extensions[extension_id] = xml_path
       end
@@ -48,13 +49,6 @@ module Xmi
       def loaded_extensions
         @loaded_extensions ||= {}
       end
-
-      private
-
-      def derive_module_name(xml_path)
-        xmi_doc = Nokogiri::XML(File.read(xml_path))
-        get_module_name(xmi_doc)
-      end
     end
   end
 end

data/lib/xmi/namespace_detector.rb

@@ -10,6 +10,15 @@ module Xmi
   class NamespaceDetector
     VERSION_PATTERN = /(\d{8})/
 
+    # Regex to extract xmlns declarations without parsing the entire document.
+    # Matches both default namespace (xmlns="...") and prefixed (xmlns:foo="...").
+    # Namespace declarations are always on or near the root element, so scanning
+    # the first 8KB is sufficient for any XMI file.
+    NS_DECL_REGEX = /xmlns(?::(\w+))?\s*=\s*["']([^"']+)["']/
+
+    # How many bytes of the XML to scan for namespace declarations
+    NS_SCAN_BYTES = 8192
+
     # Namespace URI patterns for OMG specifications
     NS_PATTERNS = {
       xmi: %r{http://www\.omg\.org/spec/XMI/(\d{8})},
@@ -33,11 +42,34 @@ module Xmi
       }
     end
 
-    # Extract all namespace URIs from XML content
+    # Extract all namespace URIs from XML content using regex on the first 8KB.
     #
-    # @param xml_content [String] The XML content to parse
+    # This avoids a full Nokogiri parse — namespace declarations are always
+    # on or near the root element, so scanning the first few KB is sufficient
+    # and ~10x faster than parsing a 3.5MB document.
+    #
+    # @param xml_content [String] The XML content
     # @return [Hash<String, String>] A hash mapping prefixes to namespace URIs
     def self.extract_namespace_uris(xml_content)
+      head = xml_content.byteslice(0, NS_SCAN_BYTES)
+      unless head.valid_encoding?
+        head = head.encode("UTF-8", invalid: :replace,
+                                    undef: :replace)
+      end
+      result = {}
+      head.scan(NS_DECL_REGEX) do |prefix, uri|
+        key = prefix.nil? ? "xmlns" : prefix
+        result[key] = uri unless result.key?(key)
+      end
+      result
+    end
+
+    # Extract namespace URIs via Nokogiri (full parse).
+    # Used by `analyze` when the complete namespace map is needed.
+    #
+    # @param xml_content [String] The XML content
+    # @return [Hash<String, String>] A hash mapping prefixes to namespace URIs
+    def self.extract_namespace_uris_full(xml_content)
       doc = Nokogiri::XML(xml_content, &:noent)
       doc.collect_namespaces
     rescue Nokogiri::XML::SyntaxError
@@ -117,7 +149,7 @@ module Xmi
     def self.analyze(xml_content)
       versions = detect_versions(xml_content)
       uris = detect_namespace_uris(xml_content)
-      raw_namespaces = extract_namespace_uris(xml_content)
+      raw_namespaces = extract_namespace_uris_full(xml_content)
 
       {
         versions: versions,

data/lib/xmi/parser_pipeline.rb

@@ -8,9 +8,9 @@ module Xmi
   # without modifying existing code — Open/Closed Principle.
   #
   # @example
-  #   context = { xml: xml_content, root_class: Xmi::Sparx::SparxRoot }
+  #   context = { xml: xml_content, root_class: Xmi::Sparx::Root }
   #   result = Xmi::ParserPipeline.run(context)
-  #   result[:root]  # => parsed SparxRoot instance
+  #   result[:root]  # => parsed Root instance
   #
   module ParserPipeline
     module Steps
@@ -18,11 +18,11 @@ module Xmi
         def self.call(ctx)
           xml = ctx[:xml]
           if xml.respond_to?(:valid_encoding?) && !xml.valid_encoding?
-            xml = xml
+            ctx[:xml] = xml
               .encode("UTF-16be", invalid: :replace, replace: "?")
               .encode("UTF-8")
           end
-          ctx.merge(xml: xml)
+          ctx
         end
       end
 
@@ -36,16 +36,16 @@ module Xmi
       module ParseXml
         def self.call(ctx)
           root_class = ctx[:root_class]
-          root = VersionRegistry.parse_with_detected_version(ctx[:xml],
-                                                             root_class)
-          ctx.merge(root: root)
+          ctx[:root] = VersionRegistry.parse_with_detected_version(
+            ctx[:xml], root_class
+          )
+          ctx
         end
       end
 
       module BuildIndex
         def self.call(ctx)
-          root = ctx[:root]
-          root.build_index if root.respond_to?(:build_index)
+          ctx[:root].build_index if ctx[:root].respond_to?(:build_index)
           ctx
         end
       end

data/lib/xmi/sparx/index.rb

@@ -2,7 +2,7 @@
 
 module Xmi
   module Sparx
-    # Builds all commonly needed indexes from a parsed SparxRoot in a single
+    # Builds all commonly needed indexes from a parsed Root in a single
     # targeted walk, avoiding the generic map_id_name approach that visits every
     # attribute of every node.
     #
@@ -24,7 +24,7 @@ module Xmi
 
       PackagedElement = ::Xmi::Uml::PackagedElement
 
-      # @param root [Xmi::Sparx::SparxRoot] parsed XMI model
+      # @param root [Xmi::Sparx::Root] parsed XMI model
       def initialize(root)
         @id_name_map = {}
         @packaged_elements = []

data/lib/xmi/sparx/mappings/base_mapping.rb

@@ -2,15 +2,15 @@
 
 module Xmi
   module Sparx
-    module SparxMappings
+    module Mappings
       # Base XML mapping class for Sparx EA XMI documents.
       #
       # This reusable mapping class encapsulates all the XML element → attribute
-      # mappings for SparxRoot.
+      # mappings for Root.
       #
       # @example Use in a model class
-      #   class SparxRoot < Root
-      #     xml SparxMappings::BaseMapping
+      #   class Root < ::Xmi::Root
+      #     xml Mappings::BaseMapping
       #   end
       class BaseMapping < Lutaml::Xml::Mapping
         xml do

data/lib/xmi/sparx/mappings.rb

@@ -2,7 +2,7 @@
 
 module Xmi
   module Sparx
-    module SparxMappings
+    module Mappings
       # Reusable XML mapping classes for Sparx EA XMI documents.
       autoload :BaseMapping, "xmi/sparx/mappings/base_mapping"
     end

data/lib/xmi/sparx/root.rb

@@ -2,7 +2,7 @@
 
 module Xmi
   module Sparx
-    class SparxRoot < Root
+    class Root < ::Xmi::Root
       attribute :modelica_parameter, SysPhS
 
       attribute :eauml_import, EaUml::Import, collection: true
@@ -26,7 +26,7 @@ module Xmi
         # encoding fix → version detection → XML parsing → index building.
         #
         # @param xml_content [String] The raw XMI XML content
-        # @return [SparxRoot] The parsed Ruby object with index built
+        # @return [Root] The parsed Ruby object with index built
         #
         # @see Xmi::ParserPipeline
         # @see Xmi.parse
@@ -55,7 +55,7 @@ module Xmi
       end
 
       # Use the reusable BaseMapping class instead of eval hack
-      xml SparxMappings::BaseMapping
+      xml Mappings::BaseMapping
 
       # Build index for fast lookups
       # @return [Sparx::Index]

data/lib/xmi/sparx.rb

@@ -17,8 +17,8 @@ module Xmi
     autoload :EaStub, "xmi/sparx/ea_stub"
     autoload :SysPhS, "xmi/sparx/sys_ph_s"
     autoload :Extension, "xmi/sparx/extension"
-    autoload :SparxRoot, "xmi/sparx/root"
-    autoload :SparxMappings, "xmi/sparx/mappings"
+    autoload :Root, "xmi/sparx/root"
+    autoload :Mappings, "xmi/sparx/mappings"
     autoload :Index, "xmi/sparx/index"
   end
 end

data/lib/xmi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Xmi
-  VERSION = "0.5.5"
+  VERSION = "0.5.6"
 end

data/lib/xmi/version_registry.rb

@@ -108,16 +108,15 @@ module Xmi
       #
       # @param xml_content [String] XML content
       # @param model_class [Class] The model class to parse into
+      # @param opts [Hash] Options passed through to from_xml
+      #   (e.g., import_declaration_plan: :skip)
       # @return [Object] Parsed model instance
-      def parse_with_detected_version(xml_content, model_class)
+      def parse_with_detected_version(xml_content, model_class, **opts)
         register = detect_register(xml_content)
 
-        if register
-          model_class.from_xml(xml_content, register: register)
-        else
-          # Fallback to default parsing (existing behavior)
-          model_class.from_xml(xml_content)
-        end
+        opts[:register] = register if register
+
+        model_class.from_xml(xml_content, **opts)
       end
 
       # Handle mixed namespace documents by binding additional namespace URIs
@@ -159,7 +158,11 @@ module Xmi
           # A cycle would occur if reg's fallback chain includes primary_register.
           # We check this by seeing if primary_register.id appears in reg's fallback.
           # Use add_fallback to keep Register and TypeContext in sync and invalidate caches.
-          primary_register.add_fallback(reg.id) unless reg.fallback.include?(primary_register.id)
+          # Guard: skip if primary already has this fallback to avoid unnecessary cache invalidation.
+          unless primary_register.fallback.include?(reg.id) ||
+              reg.fallback.include?(primary_register.id)
+            primary_register.add_fallback(reg.id)
+          end
         end
       end
       # rubocop:enable Metrics/CyclomaticComplexity

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xmi
 version: !ruby/object:Gem::Version
-  version: 0.5.5
+  version: 0.5.6
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-21 00:00:00.000000000 Z
+date: 2026-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model
@@ -52,10 +52,16 @@ files:
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - README.adoc
 - Rakefile
+- TODO.perf/01-eliminate-duplicate-nokogiri-parse.md
+- TODO.perf/02-read-only-fast-mode.md
+- TODO.perf/03-register-fallback-idempotency.md
+- TODO.perf/04-pipeline-hash-mutation.md
+- TODO.perf/05-ea-root-single-parse.md
 - bin/console
 - bin/setup
 - docs/migration.md