expressir 2.1.26 → 2.1.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94ad4b65c4f08a6ff1aafab5424989afee0419e94ac57fbd4715f2daca1da426
-  data.tar.gz: 21f24a38ca761ced3b7dec0070f08591190de7769e4e43150a4f87db59189ef4
+  metadata.gz: 2818d10a5113fdafcb93fef22c7520b2747b0aa6767003239e99266fbe28aacb
+  data.tar.gz: 04d9cc82b902107a07f93114ee0a59f551a0969e158e0fa50a125d49d92dd097
 SHA512:
-  metadata.gz: 1bc6510434694446b93e6df1e66682e0e737463ad130af77266fa207b0b7214a513817456ee7e42073a419d75ecdbb6adf9f7d34b0077f070269c5eff1d972d4
-  data.tar.gz: 4d44e23f91d30849da8d550b1cbadbc7628260f444eae1004500b2b5a9489ba3c62333ec7cb61c8d9a5860d1f5b1bef93464ad6c26910902ff0f44cb922150c7
+  metadata.gz: b435f41cfa13599b1547769c1052c2e9ac800f86c3282ad6ef0a5608ba77b0ee86bf31fceed7c21595019aa79e87c8327f001dea6d03ba14d1dea7a024adc5a8
+  data.tar.gz: 6c93af83e066f0288d41ec7552b4d512a0aa29626dfb8101f7268e92741989704e4131fbf76a976088b05a22187a952459461764bc18cda1f624380a46c92faf

data/.rubocop_todo.yml

@@ -1,51 +1,38 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-07-12 00:59:01 UTC using RuboCop version 1.77.0.
+# on 2025-10-13 04:55:00 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: 549
+# Offense count: 565
 # 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: 1
+# Offense count: 2
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Exclude:
+    - 'lib/expressir/commands/changes_import_eengine.rb'
     - 'lib/expressir/coverage.rb'
 
 # Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AutoCorrect, AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
+# Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
 # NotImplementedExceptions: NotImplementedError
 Lint/UnusedMethodArgument:
   Exclude:
     - 'lib/expressir/express/cache.rb'
     - 'lib/expressir/express/parser.rb'
 
-# Offense count: 79
+# Offense count: 83
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
-  Exclude:
-    - 'lib/expressir/benchmark.rb'
-    - 'lib/expressir/commands/benchmark.rb'
-    - 'lib/expressir/commands/benchmark_cache.rb'
-    - 'lib/expressir/commands/coverage.rb'
-    - 'lib/expressir/commands/validate.rb'
-    - 'lib/expressir/config.rb'
-    - 'lib/expressir/coverage.rb'
-    - 'lib/expressir/express/formatter.rb'
-    - 'lib/expressir/express/hyperlink_formatter.rb'
-    - 'lib/expressir/express/parser.rb'
-    - 'lib/expressir/express/resolve_references_model_visitor.rb'
-    - 'lib/expressir/express/visitor.rb'
-    - 'lib/expressir/model/declarations/schema.rb'
-    - 'lib/expressir/model/model_element.rb'
+  Enabled: false
 
 # Offense count: 1
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
@@ -53,11 +40,14 @@ Metrics/AbcSize:
 Metrics/BlockLength:
   Max: 46
 
-# Offense count: 56
+# Offense count: 59
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
     - 'lib/expressir/benchmark.rb'
+    - 'lib/expressir/changes/schema_change.rb'
+    - 'lib/expressir/commands/changes_import_eengine.rb'
+    - 'lib/expressir/commands/changes_validate.rb'
     - 'lib/expressir/commands/coverage.rb'
     - 'lib/expressir/coverage.rb'
     - 'lib/expressir/express/formatter.rb'
@@ -68,16 +58,19 @@ Metrics/CyclomaticComplexity:
     - 'lib/expressir/model/model_element.rb'
     - 'spec/support/model_element_helper.rb'
 
-# Offense count: 105
+# Offense count: 110
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 106
 
-# Offense count: 44
+# Offense count: 47
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
     - 'lib/expressir/benchmark.rb'
+    - 'lib/expressir/changes/schema_change.rb'
+    - 'lib/expressir/commands/changes_import_eengine.rb'
+    - 'lib/expressir/commands/changes_validate.rb'
     - 'lib/expressir/commands/coverage.rb'
     - 'lib/expressir/coverage.rb'
     - 'lib/expressir/express/formatter.rb'
@@ -104,7 +97,7 @@ Performance/MapMethodChain:
     - 'spec/expressir/commands/coverage_ignore_files_spec.rb'
     - 'spec/expressir/coverage_spec.rb'
 
-# Offense count: 102
+# Offense count: 126
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 123
@@ -120,12 +113,7 @@ RSpec/IndexedLet:
     - 'spec/expressir/model/data_types/set_spec.rb'
     - 'spec/expressir/model/data_types/string_spec.rb'
 
-# Offense count: 1
-RSpec/IteratedExpectation:
-  Exclude:
-    - 'spec/expressir/schema_manifest_spec.rb'
-
-# Offense count: 235
+# Offense count: 257
 RSpec/MultipleExpectations:
   Max: 114
 
@@ -146,7 +134,23 @@ RSpec/RepeatedExample:
   Exclude:
     - 'spec/expressir/model/data_types/logical_spec.rb'
 
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, AllowComments.
+# SupportedStyles: empty, nil, both
+Style/EmptyElse:
+  Exclude:
+    - 'lib/expressir/commands/changes_validate.rb'
+
 # Offense count: 1
 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

@@ -76,6 +76,7 @@ $ expressir
 Commands:
   expressir benchmark FILE_OR_YAML             # Benchmark schema loading performance for a file or list of files from YAML
   expressir benchmark-cache FILE_OR_YAML       # Benchmark schema loading with caching
+  expressir changes SUBCOMMAND                 # Commands for EXPRESS Changes files
   expressir clean PATH                         # Strip remarks and prettify EXPRESS schema at PATH
   expressir format PATH                        # pretty print EXPRESS schema located at PATH
   expressir help [COMMAND]                     # Describe available commands or one specific command
@@ -667,6 +668,107 @@ The default text output displays:
 This helps identify areas of your EXPRESS schemas that need documentation
 improvement.
 
+=== EXPRESS Changes files
+
+Expressir provides commands for working with EXPRESS Changes files that track
+schema modifications across versions.
+
+==== Validating change files
+
+The `changes validate` command validates EXPRESS Changes YAML files and
+optionally normalizes them through round-trip serialization.
+
+[source, sh]
+----
+# Validate a changes file
+expressir changes validate schema.changes.yaml
+
+# Validate with verbose output
+expressir changes validate schema.changes.yaml --verbose
+
+# Validate and normalize (outputs to stdout)
+expressir changes validate schema.changes.yaml --normalize
+
+# Validate and normalize in-place
+expressir changes validate schema.changes.yaml --normalize --in-place
+
+# Validate and save normalized output to a new file
+expressir changes validate schema.changes.yaml --normalize --output normalized.yaml
+----
+
+[options="header"]
+|===
+| Option | Description
+| `--normalize` | Normalize file through round-trip serialization
+| `--in-place` | Update file in place (requires `--normalize`)
+| `--output PATH` | Output file path for normalized output
+| `--verbose` | Show verbose output with validation details
+|===
+
+The validate command performs the following checks:
+
+. Verifies the YAML file can be parsed
+. Validates against the SchemaChange model structure
+. Ensures all required fields are present
+. Checks that change items have valid types
+
+When using `--normalize`, the command:
+
+. Loads the file and validates it
+. Serializes it back to YAML with consistent formatting
+. Either outputs to stdout, saves in-place, or writes to a new file
+
+This is useful for:
+
+* **Standardizing formatting**: Ensures consistent YAML structure
+* **Catching errors early**: Validates before committing changes
+* **Cleaning up files**: Removes inconsistencies in formatting
+
+==== Importing from eengine XML
+
+The `changes import-eengine` command converts 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
+compatible with v5.2.7 of eengine output.
+
+[source, sh]
+----
+# Import and output to stdout
+expressir changes import-eengine comparison.xml schema_name "2"
+
+# Import and save to file
+expressir changes import-eengine comparison.xml schema_name "2" -o output.yaml
+
+# Import with verbose output
+expressir changes import-eengine comparison.xml schema_name "2" -o output.yaml --verbose
+
+# Append to existing changes file
+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
+|===
+
+The import command:
+
+. 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
+
+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.
+
 
 == Usage: Ruby
 
@@ -1063,6 +1165,194 @@ expressir coverage schemas.yml --format json --exclude=TYPE:SELECT
 
 
 
+== Working with EXPRESS Changes
+
+=== General
+
+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).
+
+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)
+* Support for all change types: additions, modifications, deletions
+* Support for mapping changes in ARM/MIM schemas
+
+=== Reading change files
+
+Load an existing schema change file:
+
+[source,ruby]
+----
+require "expressir/changes"
+
+# Load from file
+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}"
+
+  # 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
+end
+----
+
+=== Creating change records
+
+Create a new change schema programmatically:
+
+[source,ruby]
+----
+# Create a new empty change schema
+change_schema = Expressir::Changes::SchemaChange.new(schema: "my_schema")
+
+# Create change items
+new_entity = Expressir::Changes::ItemChange.new(
+  type: "ENTITY",
+  name: "new_entity_name"
+)
+
+modified_function = Expressir::Changes::ItemChange.new(
+  type: "FUNCTION",
+  name: "modified_function",
+  description: "Updated parameters"
+)
+
+# Add a change edition
+changes = {
+  additions: [new_entity],
+  modifications: [modified_function],
+  deletions: []
+}
+
+change_schema.add_or_update_edition(
+  "2",
+  "Added new entity and modified function",
+  changes
+)
+
+# Save to file
+change_schema.to_file("my_schema.changes.yaml")
+----
+
+=== Updating existing change files
+
+The `add_or_update_edition` method provides smart handling:
+
+* **Same version**: Replaces the existing edition
+* **Different version**: Adds a new edition
+
+[source,ruby]
+----
+# Load existing change file
+change_schema = Expressir::Changes::SchemaChange.from_file("schema.changes.yaml")
+
+# Add a new version
+changes = {
+  modifications: [
+    Expressir::Changes::ItemChange.new(type: "TYPE", name: "updated_type")
+  ]
+}
+change_schema.add_or_update_edition("3", "Modified type definition", changes)
+
+# Or replace existing version
+change_schema.add_or_update_edition("2", "Revised description", changes)
+
+# Save changes
+change_schema.to_file("schema.changes.yaml")
+----
+
+=== Change item fields
+
+Change items support the following fields:
+
+`type`:: (Required) The EXPRESS construct type (ENTITY, TYPE, FUNCTION, etc.)
+`name`:: (Required) The name of the construct
+`description`:: (Optional) Additional details about the change
+`interfaced_items`:: (Optional) For REFERENCE_FROM items
+
+[source,ruby]
+----
+item = Expressir::Changes::ItemChange.new(
+  type: "REFERENCE_FROM",
+  name: "measure_schema",
+  interfaced_items: "length_measure"
+)
+----
+
+=== Change edition fields
+
+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)
+`changes`:: General changes (alternative to mapping)
+
+[source,ruby]
+----
+edition = Expressir::Changes::EditionChange.new(
+  version: "2",
+  description: "Added support for new functionality",
+  additions: [item1, item2],
+  modifications: [item3],
+  deletions: [item4],
+  mapping: [mapping_change]
+)
+----
+
+=== Mapping changes
+
+For ARM/MIM schema mappings, use `MappingChange`:
+
+[source,ruby]
+----
+mapping_change = Expressir::Changes::MappingChange.new(
+  change: "Entity_name ENTITY mapping updated"
+)
+----
+
+=== Example change file format
+
+[source,yaml]
+----
+---
+schema: support_resource_schema
+editions:
+- version: '2'
+  description: |-
+    The definitions of the following EXPRESS entity data types were modified:
+
+    * action;
+    * action_directive;
+    * action_method.
+  additions:
+  - type: FUNCTION
+    name: type_check_function
+  modifications:
+  - type: FUNCTION
+    name: bag_to_set
+- version: '4'
+  description: |-
+    Added support for external element references.
+  additions:
+  - type: ENTITY
+    name: component_path_shape_aspect
+  modifications:
+  - type: FUNCTION
+    name: type_check_function
+----
+
 == Contributing
 
 First, thank you for contributing! We love pull requests from everyone. By

data/expressir.gemspec

@@ -36,6 +36,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "csv"
   spec.add_dependency "liquid"
   spec.add_dependency "lutaml-model"
+  spec.add_dependency "moxml"
   spec.add_dependency "parslet", "~> 2.0"
   spec.add_dependency "ruby-progressbar", "~> 1.11"
   spec.add_dependency "table_tennis"

data/lib/expressir/changes/edition_change.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "item_change"
+require_relative "mapping_change"
+
+module Expressir
+  module Changes
+    # Represents a version edition of schema changes
+    class EditionChange < Lutaml::Model::Serializable
+      attribute :version, :string
+      attribute :description, :string
+      attribute :additions, ItemChange, collection: true
+      attribute :modifications, ItemChange, collection: true
+      attribute :deletions, ItemChange, collection: true
+      attribute :mapping, MappingChange, collection: true
+      attribute :changes, MappingChange, collection: true
+
+      yaml do
+        map "version", to: :version
+        map "description", to: :description
+        map "additions", to: :additions
+        map "modifications", to: :modifications
+        map "deletions", to: :deletions
+        map "mapping", to: :mapping
+        map "changes", to: :changes
+      end
+    end
+  end
+end

data/lib/expressir/changes/item_change.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Expressir
+  module Changes
+    # Represents a single change to an EXPRESS construct
+    class ItemChange < Lutaml::Model::Serializable
+      attribute :type, :string
+      attribute :name, :string
+      attribute :description, :string
+      attribute :interfaced_items, :string
+
+      yaml do
+        map "type", to: :type
+        map "name", to: :name
+        map "description", to: :description
+        map "interfaced_items", to: :interfaced_items
+      end
+    end
+  end
+end

data/lib/expressir/changes/mapping_change.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Expressir
+  module Changes
+    # Represents a mapping change entry
+    class MappingChange < Lutaml::Model::Serializable
+      attribute :change, :string
+      attribute :description, :string
+
+      yaml do
+        map "change", to: :change
+        map "description", to: :description
+      end
+    end
+  end
+end

data/lib/expressir/changes/schema_change.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "edition_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
+
+      yaml do
+        map "schema", to: :schema
+        map "editions", to: :editions
+      end
+
+      class << self
+        # Load a SchemaChange from a YAML file
+        #
+        # @param path [String] Path to the YAML file
+        # @return [SchemaChange] The loaded schema changes
+        def from_file(path)
+          content = File.read(path)
+          # Handle empty or minimal YAML files
+          return new if content.strip == "---" || content.strip.empty?
+
+          from_yaml(content)
+        end
+      end
+
+      # Add or update a change edition 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 ||= []
+
+        # Find existing edition with this version
+        existing_index = editions.find_index do |ed|
+          ed.version == version_str
+        end
+
+        # Create new edition
+        edition = EditionChange.new(
+          version: version_str,
+          description: description,
+          additions: changes[:additions] || [],
+          modifications: changes[:modifications] || [],
+          deletions: changes[:deletions] || [],
+        )
+
+        if existing_index
+          # Replace existing edition with same version
+          editions[existing_index] = edition
+        else
+          # Add new edition
+          editions << edition
+        end
+
+        edition
+      end
+
+      # Save this SchemaChange to a YAML file
+      #
+      # @param path [String] Path where to save the file
+      # @return [Integer] Number of bytes written
+      def to_file(path)
+        File.write(path, to_yaml)
+      end
+    end
+  end
+end

data/lib/expressir/changes.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Expressir
+  # Module for EXPRESS schema change tracking and management
+  module Changes
+  end
+end
+
+require_relative "changes/schema_change"
+require_relative "changes/mapping_change"

data/lib/expressir/cli.rb

@@ -8,6 +8,7 @@ require_relative "commands/benchmark"
 require_relative "commands/benchmark_cache"
 require_relative "commands/validate"
 require_relative "commands/coverage"
+require_relative "commands/changes"
 require_relative "commands/version"
 
 module Expressir
@@ -73,6 +74,9 @@ module Expressir
       Commands::Coverage.new(options).run(paths)
     end
 
+    desc "changes SUBCOMMAND", "Commands for EXPRESS Changes files"
+    subcommand "changes", Commands::Changes
+
     desc "version", "Expressir Version"
     def version
       Commands::Version.new(options).run

data/lib/expressir/commands/changes.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Expressir
+  module Commands
+    # Thor subcommand for EXPRESS Changes file operations
+    class Changes < Thor
+      desc "validate PATH", "Validate EXPRESS Changes YAML file"
+      method_option :normalize, type: :boolean,
+                                desc: "Normalize file through round-trip serialization"
+      method_option :in_place, type: :boolean,
+                               desc: "Update file in place (requires --normalize)"
+      method_option :output, type: :string,
+                             desc: "Output file path (for normalized output)"
+      method_option :verbose, type: :boolean,
+                              desc: "Show verbose output"
+      def validate(path)
+        require_relative "changes_validate"
+        ChangesValidate.new(options).run(path)
+      end
+
+      desc "import-eengine INPUT_XML SCHEMA_NAME VERSION",
+           "Import eengine comparison XML to EXPRESS Changes YAML"
+      method_option :output, type: :string, aliases: "-o",
+                             desc: "Output YAML file path (stdout if not specified)"
+      method_option :verbose, type: :boolean,
+                              desc: "Show verbose output"
+      def import_eengine(input_xml, schema_name, version)
+        require_relative "changes_import_eengine"
+        ChangesImportEengine.call(input_xml, options[:output], schema_name,
+                                  version, **options)
+      end
+    end
+  end
+end

data/lib/expressir/commands/changes_import_eengine.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require "moxml"
+
+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)
+      end
+
+      def 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 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
+
+        # 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]
+        else
+          puts change_schema.to_yaml
+        end
+
+        change_schema
+      end
+
+      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
+
+        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
+
+      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
+
+      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)
+        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)
+        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)
+        end
+      end
+
+      def extract_item_change(node)
+        item_change = Expressir::Changes::ItemChange.new(
+          type: node["type"],
+          name: node["name"],
+        )
+
+        # Extract interfaced.items attribute if present (for interface changes)
+        if node["interfaced.items"]
+          item_change.interfaced_items = node["interfaced.items"]
+        end
+
+        item_change
+      end
+
+      def generate_description(xml_doc, xml_mode)
+        parts = []
+
+        # 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
+
+        # 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?
+        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?
+        end
+
+        parts.join("\n\n")
+      end
+    end
+  end
+end

data/lib/expressir/commands/changes_validate.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Expressir
+  module Commands
+    # Command to validate and normalize EXPRESS Changes YAML files
+    class ChangesValidate < Base
+      def run(path)
+        require "expressir/changes"
+
+        # Check if file exists
+        unless File.exist?(path)
+          exit_with_error("File not found: #{path}")
+        end
+
+        # Validate --in-place requires --normalize
+        if options[:in_place] && !options[:normalize]
+          exit_with_error("--in-place requires --normalize flag")
+        end
+
+        # Validate --in-place and --output are mutually exclusive
+        if options[:in_place] && options[:output]
+          exit_with_error("Cannot use both --in-place and --output")
+        end
+
+        begin
+          # Load and validate the file
+          say "Validating #{path}..." if options[:verbose]
+          schema_change = Expressir::Changes::SchemaChange.from_file(path)
+
+          say "✓ File is valid" if options[:verbose]
+          say "  Schema: #{schema_change.schema}" if options[:verbose]
+          say "  Editions: #{schema_change.editions.length}" if options[:verbose]
+
+          # Normalize if requested
+          if options[:normalize]
+            say "Normalizing through round-trip serialization..." if options[:verbose]
+
+            output_path = if options[:in_place]
+                            path
+                          elsif options[:output]
+                            options[:output]
+                          else
+                            # Output to stdout
+                            nil
+                          end
+
+            if output_path
+              schema_change.to_file(output_path)
+              say "✓ Normalized file written to: #{output_path}"
+            else
+              # Output to stdout
+              puts schema_change.to_yaml
+            end
+          else
+            say "✓ File is valid"
+          end
+        rescue Psych::SyntaxError => e
+          exit_with_error("Invalid YAML syntax: #{e.message}")
+        rescue StandardError => e
+          exit_with_error("Validation failed: #{e.message}")
+        end
+      end
+    end
+  end
+end

data/lib/expressir/version.rb

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

data/lib/expressir.rb

@@ -170,11 +170,20 @@ module Expressir
     autoload :Benchmark, "expressir/commands/benchmark"
     autoload :BenchmarkCache, "expressir/commands/benchmark_cache"
     autoload :Clean, "expressir/commands/clean"
+    autoload :ImportComparison, "expressir/commands/import_comparison"
     autoload :Coverage, "expressir/commands/coverage"
     autoload :Format, "expressir/commands/format"
     autoload :Validate, "expressir/commands/validate"
     autoload :Version, "expressir/commands/version"
   end
+
+  # Autoload for Changes module classes
+  module Changes
+    autoload :SchemaChange, "expressir/changes/schema_change"
+    autoload :EditionChange, "expressir/changes/edition_change"
+    autoload :ItemChange, "expressir/changes/item_change"
+    autoload :MappingChange, "expressir/changes/mapping_change"
+  end
 end
 
 require_relative "expressir/model"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: expressir
 version: !ruby/object:Gem::Version
-  version: 2.1.26
+  version: 2.1.28
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-04 00:00:00.000000000 Z
+date: 2025-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -80,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: moxml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: parslet
   requirement: !ruby/object:Gem::Requirement
@@ -169,10 +183,18 @@ files:
 - expressir.gemspec
 - 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/cli.rb
 - lib/expressir/commands/base.rb
 - lib/expressir/commands/benchmark.rb
 - lib/expressir/commands/benchmark_cache.rb
+- lib/expressir/commands/changes.rb
+- lib/expressir/commands/changes_import_eengine.rb
+- lib/expressir/commands/changes_validate.rb
 - lib/expressir/commands/clean.rb
 - lib/expressir/commands/coverage.rb
 - lib/expressir/commands/format.rb