xmi 0.5.4 → 0.5.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ffa11bdf4fbb9c95493ef25cb5662107d72e1e708d526b7a6240ed3ffcd4f99
-  data.tar.gz: ba939950443a99f5e4c402ec004f4446c9b520486faa0e90aeeaa4bfb4bc679b
+  metadata.gz: 62e6b5232df619d790a5ca7b69454d3ed6f2762bb457808436be572162867f16
+  data.tar.gz: 4adbc6c45fd9e75a2fb6612f60cb35ef47a91afe44cca8c366f8c9b17237aeab
 SHA512:
-  metadata.gz: a23e73e4194971d9e3f8b83e3b746195ad227dd812e3777c5e3d33b59498e85448a4dd4ef3177f5e297693e7efb9a8e6a7de0ed59d9c0d6e33a1fea7b58a7290
-  data.tar.gz: 3ec9666b1313e1f5d0cb426739c7add6fea48253e8d51bf72e04323e2a7213b07877af7867e267f73c70d5c6b44e8b898375d11d137a9ac01868feb2c7cd2a22
+  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-20 09:41:00 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,46 +11,13 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'xmi.gemspec'
 
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_argument, with_fixed_indentation
-Layout/ArgumentAlignment:
-  Exclude:
-    - 'lib/xmi/parser_pipeline.rb'
-    - 'lib/xmi/sparx/index.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Layout/EmptyLinesAfterModuleInclusion:
-  Exclude:
-    - 'lib/xmi/sparx/gml/shared_attributes.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
-# SupportedHashRocketStyles: key, separator, table
-# SupportedColonStyles: key, separator, table
-# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
-Layout/HashAlignment:
-  Exclude:
-    - 'lib/xmi/sparx/mappings/base_mapping.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
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
-  Exclude:
-    - 'lib/xmi/parser_pipeline.rb'
-    - 'lib/xmi/sparx/index.rb'
-
 # Offense count: 6
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: enums
@@ -59,14 +26,14 @@ Lint/ConstantDefinitionInBlock:
     - 'lib/xmi/sparx/mappings/base_mapping.rb'
     - 'spec/performance/xmi_parsing_spec.rb'
 
-# Offense count: 15
+# Offense count: 16
 # 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/ea_root.rb'
+    - 'lib/xmi/ea_root/code_generation.rb'
     - 'lib/xmi/sparx/index.rb'
     - 'lib/xmi/version_registry.rb'
     - 'spec/performance/xmi_parsing_spec.rb'
@@ -77,23 +44,25 @@ Metrics/AbcSize:
 Metrics/BlockLength:
   Max: 98
 
-# Offense count: 4
+# Offense count: 5
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
     - 'lib/tasks/performance_helpers.rb'
+    - 'lib/xmi/ea_root/code_generation.rb'
     - 'lib/xmi/sparx/index.rb'
 
-# Offense count: 29
+# Offense count: 30
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 33
+  Max: 55
 
-# Offense count: 4
+# Offense count: 5
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
     - 'lib/tasks/performance_helpers.rb'
+    - 'lib/xmi/ea_root/code_generation.rb'
     - 'lib/xmi/sparx/index.rb'
     - 'lib/xmi/version_registry.rb'
 
@@ -135,7 +104,7 @@ RSpec/DescribeClass:
     - 'spec/xmi/namespace_aliases_spec.rb'
     - 'spec/xmi/versioning_spec.rb'
 
-# Offense count: 26
+# Offense count: 30
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 33
@@ -145,7 +114,12 @@ RSpec/LeakyConstantDeclaration:
   Exclude:
     - 'spec/performance/xmi_parsing_spec.rb'
 
-# Offense count: 36
+# Offense count: 1
+RSpec/MultipleDescribes:
+  Exclude:
+    - 'spec/xmi/sparx/gml/shared_attributes_spec.rb'
+
+# Offense count: 40
 RSpec/MultipleExpectations:
   Max: 8
 
@@ -159,11 +133,19 @@ RSpec/MultipleMemoizedHelpers:
 RSpec/NestedGroups:
   Max: 4
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Style/MultilineIfModifier:
+# Offense count: 8
+# Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
+# SupportedInflectors: default, active_support
+RSpec/SpecFilePathFormat:
   Exclude:
-    - 'lib/xmi/sparx/index.rb'
+    - '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

@@ -66,21 +66,6 @@ xmi_root_model = Xmi::Sparx::Root.parse_xml(xml_content)
 Ruby classes and modules defined in XML file dynamically.
 Then, you can generate Ruby objects by `Xmi::Sparx::Root.parse_xml`.
 
-=== Output Classes and Modules Generated from Extension into Ruby Files
-
-You can also generate Ruby files directly from the XMI content:
-
-[source,ruby]
-----
-Xmi::EaRoot.load_extension(
-  input_xml_path: 'path/to/your/custom_extension.xml',
-  module_name: 'CustomModule'
-)
-Xmi::EaRoot.output_rb_file('path/to/output_file.rb')
-----
-
-This approach allows you to save the dynamically generated Ruby code to a file for further use.
-
 === Create Extension XML File
 
 If you would like to create an extension, which allows to be loaded later, you
@@ -172,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
@@ -195,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`
@@ -292,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
@@ -316,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
@@ -399,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)
 ----
 
@@ -480,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/custom_profile/abstract.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Xmi
+  module CustomProfile
+    class Abstract < Lutaml::Model::Serializable
+      attribute :base_class, :string
+
+      xml do
+        element "Abstract"
+        namespace ::Xmi::Namespace::Sparx::CustomProfile
+
+        map_attribute "base_Class", to: :base_class
+      end
+    end
+  end
+end

data/lib/xmi/custom_profile/basic_doc.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Xmi
+  module CustomProfile
+    class BasicDoc < Lutaml::Model::Serializable
+      attribute :base_class, :string
+
+      xml do
+        element "BasicDoc"
+        namespace ::Xmi::Namespace::Sparx::CustomProfile
+
+        map_attribute "base_Class", to: :base_class
+      end
+    end
+  end
+end