expressir 2.1.28 → 2.1.30

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2818d10a5113fdafcb93fef22c7520b2747b0aa6767003239e99266fbe28aacb
-  data.tar.gz: 04d9cc82b902107a07f93114ee0a59f551a0969e158e0fa50a125d49d92dd097
+  metadata.gz: 8b14a8f31cc94d89bc7229adf4ceb23a0180bc9bdf36e01024b7f1b27b638a9f
+  data.tar.gz: 249f65e92a803eac2a10a9c0717104e4e194d19b7fe30374f733e48b8807ab01
 SHA512:
-  metadata.gz: b435f41cfa13599b1547769c1052c2e9ac800f86c3282ad6ef0a5608ba77b0ee86bf31fceed7c21595019aa79e87c8327f001dea6d03ba14d1dea7a024adc5a8
-  data.tar.gz: 6c93af83e066f0288d41ec7552b4d512a0aa29626dfb8101f7268e92741989704e4131fbf76a976088b05a22187a952459461764bc18cda1f624380a46c92faf
+  metadata.gz: 7dbf61a6903ef0317b98fcbfd3b5056258b263001e81cf9150aa52a3712e7b040e2289fb8b779d1843428617f5b29002de4deb79775aa0e28182488d14ca8f2f
+  data.tar.gz: c1c6057d4618d4caf1c6af8ad39cf3c165e3ecbebc6894ffc98b47c777ec19b3a0c6c91798fcb055be3a8cc6d1e46bc69e128de87db1a512f9069d6281e3c19f

data/.rubocop_todo.yml

@@ -1,23 +1,22 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-10-13 04:55:00 UTC using RuboCop version 1.81.1.
+# on 2025-10-16 03:45:37 UTC using RuboCop version 1.81.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
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 565
+# Offense count: 562
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 2
+# Offense count: 1
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Exclude:
-    - 'lib/expressir/commands/changes_import_eengine.rb'
     - 'lib/expressir/coverage.rb'
 
 # Offense count: 2
@@ -29,7 +28,7 @@ Lint/UnusedMethodArgument:
     - 'lib/expressir/express/cache.rb'
     - 'lib/expressir/express/parser.rb'
 
-# Offense count: 83
+# Offense count: 84
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -40,7 +39,7 @@ Metrics/AbcSize:
 Metrics/BlockLength:
   Max: 46
 
-# Offense count: 59
+# Offense count: 61
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
@@ -58,12 +57,12 @@ Metrics/CyclomaticComplexity:
     - 'lib/expressir/model/model_element.rb'
     - 'spec/support/model_element_helper.rb'
 
-# Offense count: 110
+# Offense count: 114
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 106
 
-# Offense count: 47
+# Offense count: 48
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
@@ -146,11 +145,3 @@ Style/EmptyElse:
 Style/MissingRespondToMissing:
   Exclude:
     - 'lib/expressir/express/visitor.rb'
-
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: AllowMethodsWithArguments, AllowedMethods, AllowedPatterns, AllowComments.
-# AllowedMethods: define_method
-Style/SymbolProc:
-  Exclude:
-    - 'spec/expressir/commands/changes_import_eengine_spec.rb'

data/README.adoc

@@ -724,17 +724,40 @@ This is useful for:
 * **Catching errors early**: Validates before committing changes
 * **Cleaning up files**: Removes inconsistencies in formatting
 
-==== Importing from eengine XML
+==== Importing from Express Engine comparison report XML
 
-The `changes import-eengine` command converts eengine comparison XML files to
-EXPRESS Changes YAML format.
+The `changes import-eengine` command converts Express Engine (eengine) comparison
+XML files to EXPRESS Changes YAML format.
 
 The eengine compare XML format is created through
-`exp-engine-engine/kernel/compare.lisp` in the EXPRESS Engine code. Expressir is
+`exp-engine-engine/kernel/compare.lisp` in the Express Engine code. Expressir is
 compatible with v5.2.7 of eengine output.
 
+The import command:
+
+. Parses the eengine XML comparison file
+. Automatically detects the XML mode (Schema/ARM/MIM)
+. Extracts additions, modifications, and deletions
+. Converts modified objects to EXPRESS Changes item format
+. Preserves interface change information (`interfaced.items`)
+. Creates or updates an EXPRESS Changes YAML file
+. Supports appending new versions to existing files
+
+When the output file already exists:
+
+* **Same version**: Replaces the existing version with that version
+* **New version**: Adds a new version to the file
+
+This allows you to build up a complete change history incrementally across
+multiple schema versions.
+
+Syntax:
+
 [source, sh]
 ----
+# Basic syntax
+expressir changes import-eengine INPUT_XML SCHEMA_NAME VERSION [options]
+
 # Import and output to stdout
 expressir changes import-eengine comparison.xml schema_name "2"
 
@@ -748,26 +771,62 @@ expressir changes import-eengine comparison.xml schema_name "2" -o output.yaml -
 expressir changes import-eengine comparison.xml schema_name "3" -o existing.yaml
 ----
 
-[options="header"]
-|===
-| Option | Description
-| `-o, --output PATH` | Output YAML file path (stdout if not specified)
-| `--verbose` | Show verbose output
-|===
+Where:
 
-The import command:
+`INPUT_XML`:: Path to the eengine comparison XML file
+`SCHEMA_NAME`:: Name of the schema being tracked (e.g., `aic_csg`, `action_schema`)
+`VERSION`:: Version number for this set of changes (e.g., `"2"`, `"3"`)
 
-. Parses the eengine XML comparison file
-. Extracts additions, modifications, and deletions
-. Creates or updates an EXPRESS Changes YAML file
-. Supports appending new versions to existing files
+Options:
 
-When the output file already exists:
+`-o, --output PATH`:: Output YAML file path (stdout if not specified)
+`--verbose`:: Show verbose output including parsed items
+
+The command automatically detects and handles all three eengine XML comparison
+formats:
 
-* **Same version**: Replaces the existing edition with that version
-* **New version**: Adds a new edition to the file
+Schema mode:: `<schema.changes>` root element with `<schema.additions>`,
+`<schema.modifications>`, and `<schema.deletions>` sections. See API docs for
+details.
 
-This allows you to build up a complete change history incrementally.
+Example workflow for importing changes from multiple versions:
+
+.Importing multiple versions incrementally
+[example]
+[source, sh]
+----
+# Import version 2 changes
+expressir changes import-eengine v2_comparison.xml action_schema "2" \
+  -o action_schema.changes.yaml
+
+# Import version 3 changes (appends to existing file)
+expressir changes import-eengine v3_comparison.xml action_schema "3" \
+  -o action_schema.changes.yaml
+
+# Import version 4 changes (appends to existing file)
+expressir changes import-eengine v4_comparison.xml action_schema "4" \
+  -o action_schema.changes.yaml
+
+# Verify the result
+cat action_schema.changes.yaml
+----
+
+This creates a single YAML file tracking changes across all three versions:
+
+[source,yaml]
+----
+schema: action_schema
+versions:
+- version: 2
+  description: Changes from eengine comparison
+  additions: [...]
+- version: 3
+  description: Changes from eengine comparison
+  additions: [...]
+- version: 4
+  description: Changes from eengine comparison
+  additions: [...]
+----
 
 
 == Usage: Ruby
@@ -1171,15 +1230,214 @@ expressir coverage schemas.yml --format json --exclude=TYPE:SELECT
 
 Expressir provides the `Changes` module for managing and tracking changes to
 EXPRESS schemas across versions. This module implements the EXPRESS Changes YAML
-format defined by ELF (Express Language Foundation).
+format defined by ELF (Express Language Foundation) (ELF 5005).
 
 The Changes module enables:
 
 * Loading and saving schema change records from/to YAML files
 * Programmatic creation and manipulation of change records
-* Smart edition handling (replace same version, add new version)
+* Smart version handling (replace same version, add new version)
 * Support for all change types: additions, modifications, deletions
 * Support for mapping changes in ARM/MIM schemas
+* Programmatic import from Express Engine comparison XML files
+
+
+=== Importing from Express Engine XML programmatically
+
+==== General
+
+Expressir provides programmatic API access for parsing Express Engine comparison XML
+and converting it to EXPRESS Changes format.
+
+Parse Eengine XML into a structured object model:
+
+[source,ruby]
+----
+require "expressir/eengine/compare_report"
+
+# Parse from XML string
+xml_content = File.read("comparison.xml")
+report = Expressir::Eengine::CompareReport.from_xml(xml_content)
+
+# Or parse from file
+report = Expressir::Eengine::CompareReport.from_file("comparison.xml")
+----
+
+Convert Eengine XML directly to EXPRESS Changes format:
+
+[source,ruby]
+----
+require "expressir/commands/changes_import_eengine"
+
+# Parse XML and convert to SchemaChange in one step
+xml_content = File.read("comparison.xml")
+change_schema = Expressir::Commands::ChangesImportEengine.from_xml(
+  xml_content,
+  "aic_csg",      # schema name
+  "1.0"           # version
+)
+
+# Use the SchemaChange object
+change_schema.versions.first.additions.each do |item|
+  puts "#{item.type}: #{item.name}"
+  puts "  interfaced_items: #{item.interfaced_items}" if item.interfaced_items
+end
+
+# Save to file
+change_schema.to_file("output.changes.yaml")
+----
+
+==== Compare modes
+
+===== General
+
+Expressir automatically detects and parses all three Eengine XML modes.
+
+[source,ruby]
+----
+# All modes are handled automatically
+arm_report = Expressir::Eengine::CompareReport.from_file("arm_comparison.xml")
+mim_report = Expressir::Eengine::CompareReport.from_file("mim_comparison.xml")
+schema_report = Expressir::Eengine::CompareReport.from_file("schema_comparison.xml")
+
+puts arm_report.mode     # => "arm"
+puts mim_report.mode     # => "mim"
+puts schema_report.mode  # => "schema"
+----
+
+===== Schema mode
+
+`<schema.changes>` with `<schema.additions>`, `<schema.modifications>`, `<schema.deletions>`
+
+[example]
+====
+[source,xml]
+----
+<schema.changes schema_name="aic_csg">
+  <schema.additions>
+    <modified.object type="ENTITY" name="new_entity" />
+  </schema.additions>
+  <schema.modifications>
+    <modified.object type="TYPE" name="modified_type" />
+  </schema.modifications>
+  <schema.deletions>
+    <modified.object type="FUNCTION" name="removed_function" />
+  </schema.deletions>
+</schema.changes>
+----
+====
+
+===== ARM mode
+
+`<arm.changes>` root element with `<arm.additions>`,
+`<arm.modifications>`, and `<arm.deletions>` sections
+
+[example]
+====
+[source,xml]
+----
+<arm.changes schema_name="example_arm">
+  <arm.additions>
+    <modified.object type="ENTITY" name="new_arm_entity" />
+  </arm.additions>
+</arm.changes>
+----
+====
+
+
+===== MIM mode
+
+`<mim.changes>` root element with `<mim.additions>`,
+`<mim.modifications>`, and `<mim.deletions>` sections
+
+[example]
+====
+[source,xml]
+----
+<mim.changes schema_name="example_mim">
+  <mim.additions>
+    <modified.object type="ENTITY" name="new_mim_entity" />
+  </mim.additions>
+</mim.changes>
+----
+====
+
+==== Interface changes
+
+The eengine XML format tracks interface changes (USE_FROM, REFERENCE_FROM) with
+the `interfaced.items` attribute. This attribute lists the specific items being
+imported or referenced from another schema.
+
+.Example XML with interface changes
+[example]
+====
+[source,xml]
+----
+<schema.changes schema_name="aic_csg">
+  <schema.additions>
+    <modified.object type="USE_FROM" name="geometric_model_schema"
+      interfaced.items="convex_hexahedron" />
+
+    <modified.object type="USE_FROM" name="geometric_model_schema"
+      interfaced.items="cyclide_segment_solid" />
+
+    <modified.object type="REFERENCE_FROM" name="measure_schema"
+      interfaced.items="length_measure" />
+  </schema.additions>
+</schema.changes>
+----
+
+This will be converted to EXPRESS Changes YAML as:
+
+[source,yaml]
+----
+schema: aic_csg
+versions:
+- version: 2
+  description: Changes from eengine comparison
+  additions:
+  - type: USE_FROM
+    name: geometric_model_schema
+    interfaced_items: convex_hexahedron
+  - type: USE_FROM
+    name: geometric_model_schema
+    interfaced_items: cyclide_segment_solid
+  - type: REFERENCE_FROM
+    name: measure_schema
+    interfaced_items: length_measure
+----
+====
+
+Eengine XML files track interface changes (USE_FROM, REFERENCE_FROM) with the
+`interfaced.items` attribute:
+
+[source,ruby]
+----
+report = Expressir::Eengine::CompareReport.from_file("comparison.xml")
+
+# Find interface changes
+report.additions&.modified_objects&.each do |obj|
+  if obj.type == "USE_FROM" || obj.type == "REFERENCE_FROM"
+    puts "#{obj.type} #{obj.name}"
+    puts "  Items: #{obj.interfaced_items}" if obj.interfaced_items
+  end
+end
+----
+
+
+==== Supported change types
+
+The import command recognizes all standard EXPRESS construct types:
+
+* `ENTITY` - Entity definitions
+* `TYPE` - Type definitions
+* `FUNCTION` - Function definitions
+* `PROCEDURE` - Procedure definitions
+* `RULE` - Rule definitions
+* `CONSTANT` - Constant definitions
+* `USE_FROM` - Interface imports (preserves `interfaced.items`)
+* `REFERENCE_FROM` - Interface references (preserves `interfaced.items`)
+
 
 === Reading change files
 
@@ -1195,14 +1453,14 @@ change_schema = Expressir::Changes::SchemaChange.from_file("schema.changes.yaml"
 # Access schema name
 puts "Schema: #{change_schema.schema}"
 
-# Iterate through change editions
-change_schema.editions.each do |edition|
-  puts "Version #{edition.version}: #{edition.description}"
+# Iterate through change versions
+change_schema.versions.each do |version|
+  puts "Version #{version.version}: #{version.description}"
 
   # Access changes by type
-  puts "  Additions: #{edition.additions.size}" if edition.additions
-  puts "  Modifications: #{edition.modifications.size}" if edition.modifications
-  puts "  Deletions: #{edition.deletions.size}" if edition.deletions
+  puts "  Additions: #{version.additions.size}" if version.additions
+  puts "  Modifications: #{version.modifications.size}" if version.modifications
+  puts "  Deletions: #{version.deletions.size}" if version.deletions
 end
 ----
 
@@ -1227,14 +1485,14 @@ modified_function = Expressir::Changes::ItemChange.new(
   description: "Updated parameters"
 )
 
-# Add a change edition
+# Add a change version
 changes = {
   additions: [new_entity],
   modifications: [modified_function],
   deletions: []
 }
 
-change_schema.add_or_update_edition(
+change_schema.add_or_update_version(
   "2",
   "Added new entity and modified function",
   changes
@@ -1246,10 +1504,10 @@ change_schema.to_file("my_schema.changes.yaml")
 
 === Updating existing change files
 
-The `add_or_update_edition` method provides smart handling:
+The `add_or_update_version` method provides smart handling:
 
-* **Same version**: Replaces the existing edition
-* **Different version**: Adds a new edition
+* **Same version**: Replaces the existing version
+* **Different version**: Adds a new version
 
 [source,ruby]
 ----
@@ -1262,10 +1520,10 @@ changes = {
     Expressir::Changes::ItemChange.new(type: "TYPE", name: "updated_type")
   ]
 }
-change_schema.add_or_update_edition("3", "Modified type definition", changes)
+change_schema.add_or_update_version("3", "Modified type definition", changes)
 
 # Or replace existing version
-change_schema.add_or_update_edition("2", "Revised description", changes)
+change_schema.add_or_update_version("2", "Revised description", changes)
 
 # Save changes
 change_schema.to_file("schema.changes.yaml")
@@ -1289,25 +1547,25 @@ item = Expressir::Changes::ItemChange.new(
 )
 ----
 
-=== Change edition fields
+=== Change version fields
 
-Change editions support categorizing changes into:
+Change versions support categorizing changes into:
 
 `additions`:: New elements added to the schema
 `modifications`:: Existing elements that were modified
 `deletions`:: Elements removed from the schema
-`mapping`:: Mapping-related changes (for ARM/MIM modules)
+`mappings`:: Mapping-related changes (for ARM/MIM modules)
 `changes`:: General changes (alternative to mapping)
 
 [source,ruby]
 ----
-edition = Expressir::Changes::EditionChange.new(
+version = Expressir::Changes::VersionChange.new(
   version: "2",
   description: "Added support for new functionality",
   additions: [item1, item2],
   modifications: [item3],
   deletions: [item4],
-  mapping: [mapping_change]
+  mappings: [mapping_change]
 )
 ----
 
@@ -1328,8 +1586,8 @@ mapping_change = Expressir::Changes::MappingChange.new(
 ----
 ---
 schema: support_resource_schema
-editions:
-- version: '2'
+versions:
+- version: 2
   description: |-
     The definitions of the following EXPRESS entity data types were modified:
 
@@ -1342,7 +1600,7 @@ editions:
   modifications:
   - type: FUNCTION
     name: bag_to_set
-- version: '4'
+- version: 4
   description: |-
     Added support for external element references.
   additions:

data/lib/expressir/changes/item_change.rb

@@ -8,7 +8,7 @@ module Expressir
     class ItemChange < Lutaml::Model::Serializable
       attribute :type, :string
       attribute :name, :string
-      attribute :description, :string
+      attribute :description, :string, collection: true
       attribute :interfaced_items, :string
 
       yaml do

data/lib/expressir/changes/mapping_change.rb

@@ -6,11 +6,11 @@ module Expressir
   module Changes
     # Represents a mapping change entry
     class MappingChange < Lutaml::Model::Serializable
-      attribute :change, :string
+      attribute :name, :string
       attribute :description, :string
 
       yaml do
-        map "change", to: :change
+        map "name", to: :name
         map "description", to: :description
       end
     end

data/lib/expressir/changes/schema_change.rb

@@ -1,18 +1,18 @@
 # frozen_string_literal: true
 
 require "lutaml/model"
-require_relative "edition_change"
+require_relative "version_change"
 
 module Expressir
   module Changes
     # Represents changes to an EXPRESS schema across multiple versions
     class SchemaChange < Lutaml::Model::Serializable
       attribute :schema, :string
-      attribute :editions, EditionChange, collection: true
+      attribute :versions, VersionChange, collection: true
 
       yaml do
         map "schema", to: :schema
-        map "editions", to: :editions
+        map "versions", to: :versions
       end
 
       class << self
@@ -23,32 +23,40 @@ module Expressir
         def from_file(path)
           content = File.read(path)
           # Handle empty or minimal YAML files
+          # Skip leading comments and empty lines
+          lines = content.lines
+          yaml_start_index = lines.find_index do |line|
+            !line.strip.start_with?("#") && !line.strip.empty?
+          end
+
+          if yaml_start_index
+            content = lines[yaml_start_index..].join
+          end
+
           return new if content.strip == "---" || content.strip.empty?
 
           from_yaml(content)
         end
       end
 
-      # Add or update a change edition in this schema
+      # Add or update a change version in this schema
       #
       # @param version [String] Version number
       # @param description [String] Description of changes
       # @param changes [Hash] Hash with :additions, :modifications, :deletions
-      # @return [EditionChange] The added or updated edition
-      def add_or_update_edition(version, description, changes)
-        version_str = version.to_s
-
-        # Initialize editions array if nil
-        self.editions ||= []
+      # @return [VersionChange] The added or updated version
+      def add_or_update_version(version, description, changes)
+        # Initialize versions array if nil
+        self.versions ||= []
 
-        # Find existing edition with this version
-        existing_index = editions.find_index do |ed|
-          ed.version == version_str
+        # Find existing version with this version
+        existing_index = versions.find_index do |ed|
+          ed.version == version
         end
 
-        # Create new edition
-        edition = EditionChange.new(
-          version: version_str,
+        # Create new version
+        version = VersionChange.new(
+          version: version,
           description: description,
           additions: changes[:additions] || [],
           modifications: changes[:modifications] || [],
@@ -56,14 +64,14 @@ module Expressir
         )
 
         if existing_index
-          # Replace existing edition with same version
-          editions[existing_index] = edition
+          # Replace existing version with same version
+          versions[existing_index] = version
         else
-          # Add new edition
-          editions << edition
+          # Add new version
+          versions << version
         end
 
-        edition
+        version
       end
 
       # Save this SchemaChange to a YAML file
@@ -71,7 +79,9 @@ module Expressir
       # @param path [String] Path where to save the file
       # @return [Integer] Number of bytes written
       def to_file(path)
-        File.write(path, to_yaml)
+        # Add schema hint for editor support
+        content = "# yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/schema_changes.yaml\n#{to_yaml}"
+        File.write(path, content)
       end
     end
   end

data/lib/expressir/changes/{edition_change.rb → version_change.rb}

@@ -6,14 +6,14 @@ require_relative "mapping_change"
 
 module Expressir
   module Changes
-    # Represents a version edition of schema changes
-    class EditionChange < Lutaml::Model::Serializable
-      attribute :version, :string
+    # Represents a version version of schema changes
+    class VersionChange < Lutaml::Model::Serializable
+      attribute :version, :integer
       attribute :description, :string
       attribute :additions, ItemChange, collection: true
       attribute :modifications, ItemChange, collection: true
       attribute :deletions, ItemChange, collection: true
-      attribute :mapping, MappingChange, collection: true
+      attribute :mappings, MappingChange, collection: true
       attribute :changes, MappingChange, collection: true
 
       yaml do
@@ -22,7 +22,7 @@ module Expressir
         map "additions", to: :additions
         map "modifications", to: :modifications
         map "deletions", to: :deletions
-        map "mapping", to: :mapping
+        map "mappings", to: :mappings
         map "changes", to: :changes
       end
     end

data/lib/expressir/commands/changes_import_eengine.rb

@@ -1,41 +1,44 @@
 # frozen_string_literal: true
 
 require_relative "base"
-require "moxml"
+require_relative "../eengine/compare_report"
 
 module Expressir
   module Commands
     # Command to import eengine comparison XML to EXPRESS Changes YAML
     class ChangesImportEengine < Base
-      def self.call(input_file, output_file, schema_name, version, **options)
-        new.call(input_file, output_file, schema_name, version, **options)
+      # Parse XML string and convert to SchemaChange
+      #
+      # @param xml_content [String] Eengine XML content
+      # @param schema_name [String] Schema name
+      # @param version [String] Version identifier
+      # @param options [Hash] Additional options
+      # @return [Expressir::Changes::SchemaChange]
+      def self.from_xml(xml_content, schema_name, version, **options)
+        require "expressir/changes"
+
+        # Parse into CompareReport using Lutaml::Model
+        compare_report = Expressir::Eengine::CompareReport.from_xml(xml_content)
+
+        # Convert to SchemaChange
+        convert_to_schema_change(compare_report, schema_name, version,
+                                 xml_content: xml_content, **options)
       end
 
-      def call(input_file, output_file, schema_name, version, **options)
+      # File-based workflow (backward compatible)
+      def self.call(input_file, output_file, schema_name, version, **options)
         require "expressir/changes"
 
-        # Parse the eengine XML using Moxml
         xml_content = File.read(input_file)
-        xml_doc = Moxml.new.parse(xml_content)
-
-        # Detect XML mode from root element
-        xml_mode = detect_xml_mode(xml_doc)
 
-        # Extract changes from XML
-        changes = extract_changes(xml_doc, xml_mode)
-        description = generate_description(xml_doc, xml_mode)
+        # Load existing schema if output file exists
+        existing_schema = if output_file && File.exist?(output_file) && File.size(output_file).positive?
+                            Expressir::Changes::SchemaChange.from_file(output_file)
+                          end
 
-        # Load or create change schema
-        change_schema = if output_file && File.exist?(output_file) && File.size(output_file).positive?
-                          Expressir::Changes::SchemaChange.from_file(output_file)
-                        else
-                          Expressir::Changes::SchemaChange.new(schema: schema_name)
-                        end
+        change_schema = from_xml(xml_content, schema_name, version,
+                                 existing_schema: existing_schema, **options)
 
-        # Add or update edition
-        change_schema.add_or_update_edition(version, description, changes)
-
-        # Save to file
         if output_file
           change_schema.to_file(output_file)
           puts "Change YAML file written to: #{output_file}" if options[:verbose]
@@ -46,91 +49,126 @@ module Expressir
         change_schema
       end
 
-      private
+      class << self
+        private
 
-      # Detect XML mode from root element (arm, mim, or schema)
-      def detect_xml_mode(xml_doc)
-        root = xml_doc.root
-        return nil unless root
+        def convert_to_schema_change(compare_report, schema_name, version,
+**options)
+          require "expressir/changes"
 
-        case root.name
-        when "arm.changes"
-          "arm"
-        when "mim.changes"
-          "mim"
-        when "schema.changes"
-          "schema"
-        else
-          # Default to schema mode if unrecognized
-          "schema"
-        end
-      end
+          # Extract changes from CompareReport
+          changes = {
+            additions: extract_items(compare_report.additions,
+                                     options[:xml_content]),
+            modifications: extract_items(compare_report.modifications,
+                                         options[:xml_content]),
+            deletions: extract_items(compare_report.deletions,
+                                     options[:xml_content]),
+          }
 
-      def extract_changes(xml_doc, xml_mode)
-        {
-          additions: extract_added_objects(xml_doc, xml_mode),
-          modifications: extract_modified_objects(xml_doc, xml_mode),
-          deletions: extract_deleted_objects(xml_doc, xml_mode),
-        }
-      end
+          # Use existing schema or create new one
+          change_schema = options[:existing_schema] ||
+            Expressir::Changes::SchemaChange.new(schema: schema_name)
 
-      def extract_modified_objects(xml_doc, xml_mode)
-        xpath = "//#{xml_mode}.modifications/modified.object"
-        xml_doc.xpath(xpath).map do |node|
-          extract_item_change(node)
+          # No version-level description from eengine (only item-level)
+          change_schema.add_or_update_version(version, nil, changes)
+
+          change_schema
         end
-      end
 
-      def extract_added_objects(xml_doc, xml_mode)
-        xpath = "//#{xml_mode}.additions/modified.object"
-        xml_doc.xpath(xpath).map do |node|
-          extract_item_change(node)
+        def extract_items(changes_section, xml_content)
+          return [] unless changes_section&.modified_objects
+
+          # Extract descriptions from XML as arrays
+          descriptions = extract_descriptions_from_xml(xml_content)
+
+          changes_section.modified_objects.map do |obj|
+            Expressir::Changes::ItemChange.new(
+              type: obj.type,
+              name: obj.name,
+              interfaced_items: obj.interfaced_items,
+              description: descriptions[obj.name],
+            )
+          end
         end
-      end
 
-      def extract_deleted_objects(xml_doc, xml_mode)
-        xpath = "//#{xml_mode}.deletions/modified.object"
-        xml_doc.xpath(xpath).map do |node|
-          extract_item_change(node)
+        def extract_descriptions_from_xml(xml_content)
+          return {} unless xml_content
+
+          require "nokogiri"
+          doc = Nokogiri::XML(xml_content)
+
+          doc.xpath("//modified.object").each_with_object({}) do |node, result|
+            name = node["name"]
+            desc_node = node.at_xpath("description")
+            next unless desc_node
+
+            html = desc_node.inner_html.strip
+            next if html.empty?
+
+            # Extract <li> elements or use text content
+            li_elements = Nokogiri::HTML.fragment(html).css("li")
+            result[name] = if li_elements.any?
+                             li_elements.map do |li|
+                               li.text.strip
+                             end.reject(&:empty?)
+                           else
+                             [Nokogiri::HTML.fragment(html).text.strip]
+                           end
+          end
         end
-      end
 
-      def extract_item_change(node)
-        item_change = Expressir::Changes::ItemChange.new(
-          type: node["type"],
-          name: node["name"],
-        )
+        def extract_description(compare_report)
+          parts = []
 
-        # Extract interfaced.items attribute if present (for interface changes)
-        if node["interfaced.items"]
-          item_change.interfaced_items = node["interfaced.items"]
-        end
+          [compare_report.modifications, compare_report.additions,
+           compare_report.deletions].each do |section|
+            next unless section&.modified_objects
 
-        item_change
-      end
+            section.modified_objects.each do |obj|
+              next unless obj.description
 
-      def generate_description(xml_doc, xml_mode)
-        parts = []
+              description_text = normalize_description(obj.description)
+              next if description_text.strip.empty?
 
-        # Get descriptions from modifications
-        xml_doc.xpath("//#{xml_mode}.modifications/modified.object/description").each do |desc|
-          text = desc.text.strip
-          parts << text unless text.empty?
-        end
+              parts << convert_html_to_asciidoc(description_text.strip)
+            end
+          end
 
-        # Get descriptions from additions
-        xml_doc.xpath("//#{xml_mode}.additions/modified.object/description").each do |desc|
-          text = desc.text.strip
-          parts << text unless text.empty?
+          parts.empty? ? nil : parts.join("\n\n")
         end
 
-        # Get descriptions from deletions
-        xml_doc.xpath("//#{xml_mode}.deletions/modified.object/description").each do |desc|
-          text = desc.text.strip
-          parts << text unless text.empty?
+        def normalize_description(description)
+          # Handle both String and Array (when XML has nested elements)
+          case description
+          when String
+            description
+          when Array
+            # Join array elements, handling nested structures
+            description.map { |elem| normalize_description(elem) }.join("\n")
+          when Hash
+            # Handle hash elements (from XML parsing)
+            if description.key?("__text__")
+              description["__text__"]
+            else
+              description.values.map { |v| normalize_description(v) }.join("\n")
+            end
+          else
+            description.to_s
+          end
         end
 
-        parts.join("\n\n")
+        def convert_html_to_asciidoc(text)
+          # Convert <ul><li>...</li></ul> to AsciiDoc list format
+          text = text.gsub(%r{<ul>\s*}i, "")
+          text = text.gsub(%r{\s*</ul>}i, "")
+          text = text.gsub(%r{<li>(.*?)</li>}im) do
+            "* #{Regexp.last_match(1).strip}"
+          end
+
+          # Clean up any extra whitespace
+          text.strip
+        end
       end
     end
   end

data/lib/expressir/commands/changes_validate.rb

@@ -31,7 +31,7 @@ module Expressir
 
           say "✓ File is valid" if options[:verbose]
           say "  Schema: #{schema_change.schema}" if options[:verbose]
-          say "  Editions: #{schema_change.editions.length}" if options[:verbose]
+          say "  Versions: #{schema_change.versions.length}" if options[:verbose]
 
           # Normalize if requested
           if options[:normalize]

data/lib/expressir/eengine/arm_compare_report.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "changes_section"
+require_relative "modified_object"
+
+module Expressir
+  module Eengine
+    # Represents an Eengine ARM comparison XML report
+    class ArmCompareReport < Lutaml::Model::Serializable
+      attribute :modifications, ChangesSection
+      attribute :additions, ChangesSection
+      attribute :deletions, ChangesSection
+
+      xml do
+        root "arm.changes"
+        map_element "arm.modifications", to: :modifications
+        map_element "arm.additions", to: :additions
+        map_element "arm.deletions", to: :deletions
+      end
+
+      def mode
+        "arm"
+      end
+    end
+  end
+end

data/lib/expressir/eengine/changes_section.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "modified_object"
+
+module Expressir
+  module Eengine
+    # Represents a section of changes (modifications, additions, or deletions)
+    # in an Eengine comparison report
+    class ChangesSection < Lutaml::Model::Serializable
+      attribute :modified_objects, ModifiedObject, collection: true
+
+      xml do
+        root "changes.section"
+        map_element "modified.object", to: :modified_objects
+      end
+    end
+  end
+end

data/lib/expressir/eengine/compare_report.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+Lutaml::Model::Config.configure do |config|
+  require "lutaml/model/xml_adapter/nokogiri_adapter"
+  config.xml_adapter = Lutaml::Model::XmlAdapter::NokogiriAdapter
+end
+
+require_relative "changes_section"
+require_relative "modified_object"
+require_relative "arm_compare_report"
+require_relative "mim_compare_report"
+
+module Expressir
+  module Eengine
+    # Represents an Eengine comparison XML report
+    # Supports three modes: ARM, MIM, and Schema
+    class CompareReport < Lutaml::Model::Serializable
+      attribute :modifications, ChangesSection
+      attribute :additions, ChangesSection
+      attribute :deletions, ChangesSection
+
+      xml do
+        root "schema.changes"
+        map_element "schema.modifications", to: :modifications
+        map_element "schema.additions", to: :additions
+        map_element "schema.deletions", to: :deletions
+      end
+
+      class << self
+        # Parse XML and return appropriate report class based on mode
+        #
+        # @param xml_content [String] XML content
+        # @return [CompareReport, ArmCompareReport, MimCompareReport]
+        def from_xml(xml_content)
+          mode = detect_mode(xml_content)
+
+          case mode
+          when "arm"
+            ArmCompareReport.from_xml(xml_content)
+          when "mim"
+            MimCompareReport.from_xml(xml_content)
+          else
+            super
+          end
+        end
+
+        # Load a CompareReport from an XML file
+        #
+        # @param path [String] Path to the XML file
+        # @return [CompareReport] The loaded comparison report
+        def from_file(path)
+          from_xml(File.read(path))
+        end
+
+        private
+
+        # Detect XML mode from content
+        #
+        # @param xml_content [String] XML content
+        # @return [String] "arm", "mim", or "schema"
+        def detect_mode(xml_content)
+          if xml_content.include?("<arm.changes")
+            "arm"
+          elsif xml_content.include?("<mim.changes")
+            "mim"
+          else
+            "schema"
+          end
+        end
+      end
+
+      # Detect XML mode from the report
+      # @return [String] "arm", "mim", or "schema"
+      def mode
+        "schema"
+      end
+    end
+  end
+end

data/lib/expressir/eengine/mim_compare_report.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "changes_section"
+require_relative "modified_object"
+
+module Expressir
+  module Eengine
+    # Represents an Eengine MIM comparison XML report
+    class MimCompareReport < Lutaml::Model::Serializable
+      attribute :modifications, ChangesSection
+      attribute :additions, ChangesSection
+      attribute :deletions, ChangesSection
+
+      xml do
+        root "mim.changes"
+        map_element "mim.modifications", to: :modifications
+        map_element "mim.additions", to: :additions
+        map_element "mim.deletions", to: :deletions
+      end
+
+      def mode
+        "mim"
+      end
+    end
+  end
+end

data/lib/expressir/eengine/modified_object.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Expressir
+  module Eengine
+    # Represents a modified EXPRESS object in an Eengine comparison report
+    class ModifiedObject < Lutaml::Model::Serializable
+      attribute :type, :string
+      attribute :name, :string
+      attribute :interfaced_items, :string
+      attribute :description, :string
+
+      xml do
+        root "modified.object"
+        map_attribute "type", to: :type
+        map_attribute "name", to: :name
+        map_attribute "interfaced.items", to: :interfaced_items
+        map_element "description", to: :description
+      end
+    end
+  end
+end

data/lib/expressir/version.rb

@@ -1,3 +1,3 @@
 module Expressir
-  VERSION = "2.1.28".freeze
+  VERSION = "2.1.30".freeze
 end

data/lib/expressir.rb

@@ -180,7 +180,7 @@ module Expressir
   # Autoload for Changes module classes
   module Changes
     autoload :SchemaChange, "expressir/changes/schema_change"
-    autoload :EditionChange, "expressir/changes/edition_change"
+    autoload :VersionChange, "expressir/changes/version_change"
     autoload :ItemChange, "expressir/changes/item_change"
     autoload :MappingChange, "expressir/changes/mapping_change"
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: expressir
 version: !ruby/object:Gem::Version
-  version: 2.1.28
+  version: 2.1.30
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-13 00:00:00.000000000 Z
+date: 2025-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -184,10 +184,10 @@ files:
 - lib/expressir.rb
 - lib/expressir/benchmark.rb
 - lib/expressir/changes.rb
-- lib/expressir/changes/edition_change.rb
 - lib/expressir/changes/item_change.rb
 - lib/expressir/changes/mapping_change.rb
 - lib/expressir/changes/schema_change.rb
+- lib/expressir/changes/version_change.rb
 - lib/expressir/cli.rb
 - lib/expressir/commands/base.rb
 - lib/expressir/commands/benchmark.rb
@@ -202,6 +202,11 @@ files:
 - lib/expressir/commands/version.rb
 - lib/expressir/config.rb
 - lib/expressir/coverage.rb
+- lib/expressir/eengine/arm_compare_report.rb
+- lib/expressir/eengine/changes_section.rb
+- lib/expressir/eengine/compare_report.rb
+- lib/expressir/eengine/mim_compare_report.rb
+- lib/expressir/eengine/modified_object.rb
 - lib/expressir/express/cache.rb
 - lib/expressir/express/error.rb
 - lib/expressir/express/formatter.rb