expressir 2.1.28 → 2.1.29

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2818d10a5113fdafcb93fef22c7520b2747b0aa6767003239e99266fbe28aacb
-  data.tar.gz: 04d9cc82b902107a07f93114ee0a59f551a0969e158e0fa50a125d49d92dd097
+  metadata.gz: fbc607242e5dfe5db0276c14d37cdc1d38fc07e4f0014134b20105e443a3b96c
+  data.tar.gz: 32ba2fe11da1f6439b7a97e30215df127aa6826ae6199f205fa4376c7624a4d2
 SHA512:
-  metadata.gz: b435f41cfa13599b1547769c1052c2e9ac800f86c3282ad6ef0a5608ba77b0ee86bf31fceed7c21595019aa79e87c8327f001dea6d03ba14d1dea7a024adc5a8
-  data.tar.gz: 6c93af83e066f0288d41ec7552b4d512a0aa29626dfb8101f7268e92741989704e4131fbf76a976088b05a22187a952459461764bc18cda1f624380a46c92faf
+  metadata.gz: 06e09081cbb49ef2d4656e8f9104c830edf8fc0427ffbcef0f6fa686884468e561370656d74b3c0f893b1786e0e9d4d4d8f335d297e9e3ddb8211d9bc26bbfd1
+  data.tar.gz: 15350b06e45e272b7b7dbaee29c5030b794e67a30544344bf534ec2b86c89998fcb1123c1352201d4d41f217f8e11c3054f5e0ef3f94fccb96b3daa42aacda82

data/.rubocop_todo.yml

@@ -1,23 +1,61 @@
 # 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-15 09:12:23 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: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_argument, with_fixed_indentation
+Layout/ArgumentAlignment:
+  Exclude:
+    - 'lib/expressir/commands/changes_import_eengine.rb'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: either, start_of_block, start_of_line
+Layout/BlockAlignment:
+  Exclude:
+    - 'lib/expressir/commands/changes_import_eengine.rb'
+    - 'spec/expressir/commands/changes_import_eengine_spec.rb'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+Layout/BlockEndNewline:
+  Exclude:
+    - 'lib/expressir/commands/changes_import_eengine.rb'
+    - 'spec/expressir/commands/changes_import_eengine_spec.rb'
+
+# Offense count: 8
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, AllowedPatterns.
+Layout/IndentationWidth:
+  Exclude:
+    - 'lib/expressir/commands/changes_import_eengine.rb'
+    - 'spec/expressir/commands/changes_import_eengine_spec.rb'
+
+# Offense count: 569
 # 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: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Exclude:
+    - 'lib/expressir/commands/changes_import_eengine.rb'
+
+# 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
@@ -40,7 +78,7 @@ Metrics/AbcSize:
 Metrics/BlockLength:
   Max: 46
 
-# Offense count: 59
+# Offense count: 61
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
@@ -58,12 +96,12 @@ Metrics/CyclomaticComplexity:
     - 'lib/expressir/model/model_element.rb'
     - 'spec/support/model_element_helper.rb'
 
-# Offense count: 110
+# Offense count: 113
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 106
 
-# Offense count: 47
+# Offense count: 48
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
@@ -134,6 +172,18 @@ RSpec/RepeatedExample:
   Exclude:
     - 'spec/expressir/model/data_types/logical_spec.rb'
 
+# Offense count: 6
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# AllowedMethods: lambda, proc, it
+Style/BlockDelimiters:
+  Exclude:
+    - 'lib/expressir/commands/changes_import_eengine.rb'
+    - 'spec/expressir/commands/changes_import_eengine_spec.rb'
+
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, AllowComments.
@@ -146,11 +196,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 edition with that version
+* **New version**: Adds a new edition 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
 
-* **Same version**: Replaces the existing edition with that version
-* **New version**: Adds a new edition to the file
+The command automatically detects and handles all three eengine XML comparison
+formats:
+
+Schema mode:: `<schema.changes>` root element with `<schema.additions>`,
+`<schema.modifications>`, and `<schema.deletions>` sections. See API docs for
+details.
+
+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
 
-This allows you to build up a complete change history incrementally.
+# 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
+editions:
+- 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,7 +1230,7 @@ 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:
 
@@ -1180,6 +1239,205 @@ The Changes module enables:
 * Smart edition 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.editions.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
+editions:
+- 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
 
@@ -1296,7 +1554,7 @@ Change editions 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]
@@ -1307,7 +1565,7 @@ edition = Expressir::Changes::EditionChange.new(
   additions: [item1, item2],
   modifications: [item3],
   deletions: [item4],
-  mapping: [mapping_change]
+  mappings: [mapping_change]
 )
 ----
 

data/lib/expressir/changes/edition_change.rb

@@ -13,7 +13,7 @@ module Expressir
       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/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/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 edition-level description from eengine (only item-level)
+          change_schema.add_or_update_edition(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/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.29".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: expressir
 version: !ruby/object:Gem::Version
-  version: 2.1.28
+  version: 2.1.29
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-13 00:00:00.000000000 Z
+date: 2025-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -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