expressir 2.1.25 → 2.1.27

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f52eda5e0d80dd80576d784a17159f1f70151d1040d493e2f70408a86a269f9f
-  data.tar.gz: a5bfdc154ad38933894545b193ead0f616e07e86aa316284d86fbf3f1556f673
+  metadata.gz: 79f9083d84c90911c68536e3f07c4a2ebeb7675bca18d445b7af90d9ece6e7ee
+  data.tar.gz: 69e648f694b883906a32fc316219db79dbaa053c2633a4543cd4b62673a9f88d
 SHA512:
-  metadata.gz: 9ada0d27c2df4a16595cde9973f48e224d4a46691bad332500af178b43898f4a721bc19876ba383dc41a694ee405796495996999eb3008220aca53e978c9d3e3
-  data.tar.gz: ebdb14b2bd307482f39c8c682c68081324bfb012bf9b4cc68f511739b65f26b361e40f65fba2ae6fc50b782a04661836849c6ecd827e95f318e828221b951de3
+  metadata.gz: d9cc037357c9803c739a486089fc69b4799b1ba02f5f9de51216175447765f0e650dc02f8c525d2c4be8a3ea38e2ac953c5ef22e530ce4fea1f42f902eead456
+  data.tar.gz: aca50dfe25f95e07453607f76df4ca532a3c3e97f8d95af08442c5a5ff402434a80e3fa6b2f8147992b72fefbaa1c3b9487f001095960b605abd5a3cfecd2bf1

data/.rubocop_todo.yml

@@ -1,18 +1,116 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-07-04 10:39:56 UTC using RuboCop version 1.77.0.
+# on 2025-10-12 15:55:59 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: 550
+# Offense count: 9
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_argument, with_fixed_indentation
+Layout/ArgumentAlignment:
+  Exclude:
+    - 'lib/expressir/commands/changes.rb'
+    - 'spec/expressir/changes/schema_change_spec.rb'
+    - 'spec/expressir/commands/changes_import_eengine_spec.rb'
+    - 'spec/expressir/commands/changes_validate_spec.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: either, start_of_block, start_of_line
+Layout/BlockAlignment:
+  Exclude:
+    - 'lib/expressir/changes/schema_change.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/BlockEndNewline:
+  Exclude:
+    - 'lib/expressir/changes/schema_change.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowForAlignment.
+Layout/CommentIndentation:
+  Exclude:
+    - 'lib/expressir/commands/changes_validate.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+Layout/ElseAlignment:
+  Exclude:
+    - 'lib/expressir/commands/changes_validate.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: empty_lines, no_empty_lines
+Layout/EmptyLinesAroundBlockBody:
+  Exclude:
+    - 'bin/validate_all_changes'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith, Severity.
+# SupportedStylesAlignWith: keyword, variable, start_of_line
+Layout/EndAlignment:
+  Exclude:
+    - 'lib/expressir/commands/changes_validate.rb'
+
+# Offense count: 12
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
+# SupportedHashRocketStyles: key, separator, table
+# SupportedColonStyles: key, separator, table
+# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
+Layout/HashAlignment:
+  Exclude:
+    - 'lib/expressir/commands/changes.rb'
+    - 'spec/expressir/changes/schema_change_spec.rb'
+    - 'spec/expressir/commands/changes_validate_spec.rb'
+
+# Offense count: 6
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, AllowedPatterns.
+Layout/IndentationWidth:
+  Exclude:
+    - 'bin/validate_all_changes'
+    - 'lib/expressir/changes/schema_change.rb'
+    - 'lib/expressir/commands/changes_validate.rb'
+
+# Offense count: 574
 # 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
+# This cop supports safe autocorrection (--autocorrect).
+Layout/RescueEnsureAlignment:
+  Exclude:
+    - 'bin/validate_all_changes'
+
+# Offense count: 8
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Exclude:
+    - 'bin/validate_all_changes'
+    - 'lib/expressir/commands/changes.rb'
+    - 'spec/expressir/changes/schema_change_spec.rb'
+    - 'spec/expressir/commands/changes_import_eengine_spec.rb'
+    - 'spec/expressir/commands/changes_validate_spec.rb'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+Lint/AmbiguousOperatorPrecedence:
+  Exclude:
+    - 'bin/validate_all_changes'
+
 # Offense count: 1
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
@@ -21,43 +119,32 @@ Lint/DuplicateBranch:
 
 # 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
+# Offense count: 2
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 46
+  Max: 72
 
-# 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 +155,19 @@ Metrics/CyclomaticComplexity:
     - 'lib/expressir/model/model_element.rb'
     - 'spec/support/model_element_helper.rb'
 
-# Offense count: 105
+# Offense count: 109
 # 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 +194,7 @@ Performance/MapMethodChain:
     - 'spec/expressir/commands/coverage_ignore_files_spec.rb'
     - 'spec/expressir/coverage_spec.rb'
 
-# Offense count: 102
+# Offense count: 122
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 123
@@ -121,11 +211,12 @@ RSpec/IndexedLet:
     - 'spec/expressir/model/data_types/string_spec.rb'
 
 # Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
 RSpec/IteratedExpectation:
   Exclude:
     - 'spec/expressir/schema_manifest_spec.rb'
 
-# Offense count: 235
+# Offense count: 254
 RSpec/MultipleExpectations:
   Max: 114
 
@@ -146,7 +237,89 @@ RSpec/RepeatedExample:
   Exclude:
     - 'spec/expressir/model/data_types/logical_spec.rb'
 
+# Offense count: 2
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Security/YAMLLoad:
+  Exclude:
+    - 'bin/validate_all_changes'
+
+# Offense count: 1
+# 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/changes/schema_change.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: EnforcedStyle, AllowedMethods, AllowedPatterns.
+# SupportedStyles: predicate, comparison
+Style/NumericPredicate:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/expressir/commands/changes_import_eengine.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/RedundantBegin:
+  Exclude:
+    - 'bin/validate_all_changes'
+
+# Offense count: 4
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: Mode.
+Style/StringConcatenation:
+  Exclude:
+    - 'bin/validate_all_changes'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiteralsInInterpolation:
+  Exclude:
+    - 'bin/validate_all_changes'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleForMultiline.
+# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
+Style/TrailingCommaInArguments:
+  Exclude:
+    - 'lib/expressir/changes/schema_change.rb'
+    - 'lib/expressir/commands/changes_import_eengine.rb'
+
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleForMultiline.
+# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
+Style/TrailingCommaInArrayLiteral:
+  Exclude:
+    - 'spec/expressir/changes/schema_change_spec.rb'
+
+# Offense count: 10
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleForMultiline.
+# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
+Style/TrailingCommaInHashLiteral:
+  Exclude:
+    - 'bin/validate_all_changes'
+    - 'lib/expressir/commands/changes_import_eengine.rb'
+    - 'spec/expressir/changes/schema_change_spec.rb'

data/Gemfile

@@ -5,6 +5,7 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in reeper.gemspec
 gemspec
 
+gem "canon"
 gem "pry"
 gem "rake"
 gem "rspec"

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,103 @@ 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.
+
+[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 removals
+. 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 +1161,196 @@ 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, removals, 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.edition_change.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
+  puts "  Removals: #{edition.removals.size}" if edition.removals
+end
+----
+
+=== Creating change records
+
+Create a new change schema programmatically:
+
+[source,ruby]
+----
+# Create a new empty change schema
+change_schema = Expressir::Changes::SchemaChange.create_new("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],
+  removals: []
+}
+
+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
+`removals`:: Elements removed from the schema
+`deletions`:: Alternative term for removals (both supported)
+`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
+edition_change:
+- 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

@@ -38,6 +38,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency "lutaml-model"
   spec.add_dependency "parslet", "~> 2.0"
   spec.add_dependency "ruby-progressbar", "~> 1.11"
-  spec.add_dependency "terminal-table", "~> 3.0"
+  spec.add_dependency "table_tennis"
   spec.add_dependency "thor", "~> 1.0"
 end

data/lib/expressir/changes/edition_change.rb

@@ -0,0 +1,32 @@
+# 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 :removals, 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 "removals", to: :removals
+        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,84 @@
+# 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 :edition_change, EditionChange, collection: true
+
+      yaml do
+        map "schema", to: :schema
+        map "edition_change", to: :edition_change
+      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(schema: "", edition_change: []) if content.strip == "---"
+
+          from_yaml(content)
+        end
+
+        # Create a new empty SchemaChange
+        #
+        # @param schema_name [String] Name of the schema
+        # @return [SchemaChange] New instance with empty change editions
+        def create_new(schema_name)
+          new(schema: schema_name, edition_change: [])
+        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, :removals
+      # @return [EditionChange] The added or updated edition
+      def add_or_update_edition(version, description, changes)
+        version_str = version.to_s
+
+        # Find existing edition with this version
+        existing_index = edition_change.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] || [],
+          removals: changes[:removals] || [],
+          deletions: changes[:deletions] || [],
+        )
+
+        if existing_index
+          # Replace existing edition with same version
+          edition_change[existing_index] = edition
+        else
+          # Add new edition
+          edition_change << 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,12 @@
+# frozen_string_literal: true
+
+require_relative "changes/schema_change"
+require_relative "changes/edition_change"
+require_relative "changes/item_change"
+require_relative "changes/mapping_change"
+
+module Expressir
+  # Module for EXPRESS schema change tracking and management
+  module Changes
+  end
+end

data/lib/expressir/cli.rb

@@ -1,6 +1,5 @@
 require "thor"
 require "yaml"
-require "terminal-table"
 
 require_relative "commands/base"
 require_relative "commands/format"
@@ -9,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
@@ -74,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,107 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require "nokogiri"
+
+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
+        xml_doc = File.open(input_file) { |f| Nokogiri::XML(f) }
+
+        # Extract changes from XML
+        changes = extract_changes(xml_doc)
+        description = generate_description(xml_doc)
+
+        # 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.create_new(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
+
+      def extract_changes(xml_doc)
+        {
+          additions: extract_added_objects(xml_doc),
+          modifications: extract_modified_objects(xml_doc),
+          removals: extract_removed_objects(xml_doc),
+        }
+      end
+
+      def extract_modified_objects(xml_doc)
+        xml_doc.xpath("//schema.modifications/modified.object").map do |node|
+          Expressir::Changes::ItemChange.new(
+            type: node["type"],
+            name: node["name"],
+          )
+        end
+      end
+
+      def extract_added_objects(xml_doc)
+        xml_doc.xpath("//schema.additions/added.object").map do |node|
+          Expressir::Changes::ItemChange.new(
+            type: node["type"],
+            name: node["name"],
+          )
+        end
+      end
+
+      def extract_removed_objects(xml_doc)
+        xml_doc.xpath("//schema.removals/removed.object").map do |node|
+          Expressir::Changes::ItemChange.new(
+            type: node["type"],
+            name: node["name"],
+          )
+        end
+      end
+
+      def generate_description(xml_doc)
+        parts = []
+
+        # Get descriptions from modifications
+        xml_doc.xpath("//schema.modifications/modified.object/description").each do |desc|
+          text = desc.text.strip
+          parts << text unless text.empty?
+        end
+
+        # Get descriptions from additions
+        xml_doc.xpath("//schema.additions/added.object/description").each do |desc|
+          text = desc.text.strip
+          parts << text unless text.empty?
+        end
+
+        # Get descriptions from removals
+        xml_doc.xpath("//schema.removals/removed.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.edition_change.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/commands/coverage.rb

@@ -1,4 +1,4 @@
-require "terminal-table"
+require "table_tennis"
 require "json"
 require "yaml"
 require "ruby-progressbar"
@@ -173,55 +173,79 @@ module Expressir
           end
         end
 
-        # Create table
-        table = Terminal::Table.new(
-          title: "Directory Coverage",
-          headings: ["Directory", "Total", "Documented", "Coverage %"],
-          style: {
-            border_x: "-",
-            border_y: "|",
-            border_i: "+",
-          },
-        )
-
-        # Add rows
+        table_data = []
         dirs.each do |dir, stats|
           coverage = stats["total"].positive? ? (stats["documented"].to_f / stats["total"] * 100).round(2) : 100.0
-          table.add_row [dir, stats["total"], stats["documented"],
-                         "#{coverage}%"]
+          table_data << {
+            directory: dir,
+            total: stats["total"].to_s,
+            documented: stats["documented"].to_s,
+            coverage_percentage: "#{coverage}%",
+          }
         end
 
+        table = TableTennis.new(
+          table_data,
+          {
+            title: "Entity coverage per directory",
+            headers: {
+              file: "Directory",
+              total: "Total Entities",
+              documented: "Documented Entities",
+              coverage_percentage: "Coverage %",
+            },
+            titleize: true,
+            layout: true,
+          },
+        )
+
         say table
       end
 
       def display_file_coverage(reports)
-        say "\nFile Coverage:"
-
-        # Create table
-        table = Terminal::Table.new(
-          title: "File Coverage",
-          headings: ["File", "Undocumented Entities", "Coverage %"],
-          style: {
-            border_x: "-",
-            border_y: "|",
-            border_i: "+",
-          },
-        )
-
+        # Prepare data for table_tennis
+        table_data = []
         reports.each do |report|
           report.file_reports.each do |file_report|
             file_path = file_report["file"]
 
             # Format undocumented entities as "TYPE name, TYPE name, ..."
-            undocumented_formatted = file_report["undocumented"].map do |entity_info|
+            undocumented = file_report["undocumented"].map do |entity_info|
               "#{entity_info['type']} #{entity_info['name']}"
             end.join(", ")
 
             coverage = file_report["coverage"].round(2)
-            table.add_row [file_path, undocumented_formatted, "#{coverage}%"]
+
+            table_data << {
+              filename: File.basename(file_path),
+              undocumented_entities: if undocumented.empty?
+                                       "None"
+                                     else
+                                       undocumented
+                                     end,
+              coverage_percentage: "#{coverage}%",
+            }
           end
         end
 
+        table = TableTennis.new(
+          table_data,
+          {
+            title: "Entity coverage in file",
+            headers: {
+              filename: "Filename",
+              undocumented_entities: "Undocumented Entities",
+              coverage_percentage: "Coverage %",
+            },
+            titleize: true,
+            layout: {
+              filename: 30,
+              undocumented_entities: 50,
+              coverage_percentage: 20,
+            },
+          },
+        )
+
         say table
       end
 
@@ -229,22 +253,35 @@ module Expressir
         # Get structured report for overall statistics
         overall = build_structured_report(reports)["overall"]
 
-        table = Terminal::Table.new(
-          title: "Overall Documentation Coverage",
-          style: {
-            border_x: "-",
-            border_y: "|",
-            border_i: "+",
+        coverage_percentage = overall["coverage_percentage"]
+        table_data = [
+          {
+            metric: "Coverage Percentage",
+            value: "#{coverage_percentage}%",
+          },
+          {
+            metric: "Total Entities",
+            value: overall["total_entities"].to_s,
+          },
+          {
+            metric: "Documented Entities",
+            value: overall["documented_entities"].to_s,
+          },
+          {
+            metric: "Undocumented Entities",
+            value: overall["undocumented_entities"].to_s,
+          },
+        ]
+
+        table = TableTennis.new(
+          table_data,
+          {
+            title: "Entity overall coverage",
+            titleize: true,
+            layout: true,
           },
         )
 
-        table.add_row ["Coverage Percentage",
-                       "#{overall['coverage_percentage']}%"]
-        table.add_row ["Total Entities", overall["total_entities"]]
-        table.add_row ["Documented Entities", overall["documented_entities"]]
-        table.add_row ["Undocumented Entities",
-                       overall["undocumented_entities"]]
-
         say table
       end
 
@@ -253,6 +290,15 @@ module Expressir
         ignored_files = reports.flat_map(&:ignored_file_reports)
         ignored_entities_count = ignored_files.sum { |f| f["total"] }
 
+        total = reports.sum { |r| r.total_entities.size }
+        documented = reports.sum { |r| r.documented_entities.size }
+
+        coverage_per = if total.positive?
+                         (documented.to_f / total * 100).round(2)
+                       else
+                         100.0
+                       end
+
         overall_stats = {
           "total_entities" => reports.sum { |r| r.total_entities.size },
           "documented_entities" => reports.sum do |r|
@@ -261,17 +307,7 @@ module Expressir
           "undocumented_entities" => reports.sum do |r|
             r.undocumented_entities.size
           end,
-          "coverage_percentage" => if reports.sum do |r|
-            r.total_entities.size
-          end.positive?
-                                     (reports.sum do |r|
-                                       r.documented_entities.size
-                                     end.to_f / reports.sum do |r|
-                                                  r.total_entities.size
-                                                end * 100).round(2)
-                                   else
-                                     100.0
-                                   end,
+          "coverage_percentage" => coverage_per,
         }
 
         # Add ignored file information if there are any

data/lib/expressir/schema_manifest.rb

@@ -28,7 +28,8 @@ module Expressir
         x.set_initial_path(path)
       end
     rescue StandardError => e
-      raise InvalidSchemaManifestError, "Invalid schema manifest format: #{e.message}"
+      raise InvalidSchemaManifestError,
+            "Invalid schema manifest format: #{e.message}"
     end
 
     def to_file(to_path = path)

data/lib/expressir/version.rb

@@ -1,3 +1,3 @@
 module Expressir
-  VERSION = "2.1.25".freeze
+  VERSION = "2.1.27".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.25
+  version: 2.1.27
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-15 00:00:00.000000000 Z
+date: 2025-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -109,19 +109,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.11'
 - !ruby/object:Gem::Dependency
-  name: terminal-table
+  name: table_tennis
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -169,10 +169,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