suma 0.1.24 → 0.1.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2e8f69b5a73e7e808b0dceb8443829f1ee07370f391e29144187eac0870b3ba
-  data.tar.gz: 912fa2f86f74512f95fb25dbf082de1d65bb65848e832cab66444e1e4e698956
+  metadata.gz: 13a0618f0faf4d08efb9d7783533cad40d31b5069b20d0107ccf6535ac5dcf7f
+  data.tar.gz: c5cf074c3c75091c41828fece24dbef27c07691f8dce321ac4d6ef7f71515640
 SHA512:
-  metadata.gz: f9d9d3a67a2425b3b96d0a8ceddfa964e1d2a7a391fb626201f4ca1be98c23a96eb622d10ee5b7073c2d80be65f9d9a88b9d75996231c02da5035593aa4e7860
-  data.tar.gz: 79435485f1e2c1389a8054153e1e6abfb145f098038937c3f79d3d7a55e9b6b9ead89b78f6a2f74f462d8d71e7f726ed455e20ffd712357b58455818691eacc1
+  metadata.gz: c9f2807fcfd075246d53741d231b241300410ad847795d0c2575cc4cfc205c22d36c2d1f7c7648432be41e63e3f00ae45472382d4c201230e8eefc5cda4506bc
+  data.tar.gz: 189245d32cd54e2fef7090a2f6ee9ab67188265b4ff5ffbb3dd71436ccf832b618f27f2005f97c8bf9ee29db43453063b9b18f4e6f6a4e983ddc5e1c99fa9b53

data/.rubocop.yml

@@ -1,6 +1,6 @@
 inherit_from:
-  - .rubocop_todo.yml
   - https://raw.githubusercontent.com/riboseinc/oss-guides/main/ci/rubocop.yml
+  - .rubocop_todo.yml
 
 plugins:
 - rubocop-performance

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-10-12 09:15:38 UTC using RuboCop version 1.81.1.
+# on 2025-10-16 10:57:12 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
@@ -18,55 +18,20 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'suma.gemspec'
 
-# Offense count: 2
+# Offense count: 84
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_argument, with_fixed_indentation
-Layout/ArgumentAlignment:
-  Exclude:
-    - 'spec/suma/cli/export_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:
-    - 'spec/suma/cli/export_spec.rb'
+# 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/BlockEndNewline:
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: final_newline, final_blank_line
+Layout/TrailingEmptyLines:
   Exclude:
-    - 'spec/suma/cli/export_spec.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Width, AllowedPatterns.
-Layout/IndentationWidth:
-  Exclude:
-    - 'spec/suma/cli/export_spec.rb'
-
-# Offense count: 74
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
-# URISchemes: http, https
-Layout/LineLength:
-  Exclude:
-    - 'lib/suma/cli/build.rb'
-    - 'lib/suma/cli/validate.rb'
-    - 'lib/suma/collection_manifest.rb'
-    - 'lib/suma/jsdai/figure.rb'
-    - 'lib/suma/jsdai/figure_image.rb'
-    - 'lib/suma/processor.rb'
-    - 'lib/suma/schema_attachment.rb'
-    - 'lib/suma/schema_document.rb'
-    - 'lib/suma/thor_ext.rb'
-    - 'spec/suma/cli/export_spec.rb'
-    - 'spec/suma/cli/extract_terms_spec.rb'
-    - 'spec/suma/cli/validate_ascii_spec.rb'
-    - 'spec/suma/jsdai/figure_spec.rb'
-    - 'suma.gemspec'
+    - 'Gemfile'
 
 # Offense count: 2
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
@@ -84,30 +49,48 @@ Lint/IneffectiveAccessModifier:
   Exclude:
     - 'lib/suma/cli/export.rb'
 
-# Offense count: 9
+# Offense count: 11
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
+    - 'lib/suma/cli/compare.rb'
     - 'lib/suma/jsdai/figure.rb'
     - 'lib/suma/jsdai/figure_image.rb'
     - 'lib/suma/schema_attachment.rb'
     - 'lib/suma/schema_document.rb'
     - 'lib/suma/thor_ext.rb'
 
-# Offense count: 3
+# Offense count: 6
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
+    - 'lib/suma/cli/compare.rb'
+    - 'lib/suma/eengine/wrapper.rb'
     - 'lib/suma/jsdai/figure.rb'
     - 'lib/suma/jsdai/figure_image.rb'
     - 'lib/suma/thor_ext.rb'
 
-# Offense count: 1
+# Offense count: 5
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Max: 60
+
+# Offense count: 4
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
+    - 'lib/suma/cli/compare.rb'
+    - 'lib/suma/eengine/wrapper.rb'
     - 'lib/suma/jsdai/figure_image.rb'
 
+# Offense count: 1
+# Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
+# AllowedMethods: call
+# WaywardPredicates: nonzero?
+Naming/PredicateMethod:
+  Exclude:
+    - 'lib/suma/eengine/wrapper.rb'
+
 # Offense count: 6
 # Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
 # SupportedStyles: snake_case, normalcase, non_integer
@@ -117,10 +100,11 @@ Naming/VariableNumber:
     - 'spec/suma/cli/export_spec.rb'
     - 'spec/suma/cli/validate_ascii_spec.rb'
 
-# Offense count: 2
+# Offense count: 3
 # Configuration parameters: MinSize.
 Performance/CollectionLiteralInLoop:
   Exclude:
+    - 'spec/suma/cli/compare_spec.rb'
     - 'spec/suma/cli/export_spec.rb'
     - 'spec/suma/cli_spec.rb'
 
@@ -131,20 +115,40 @@ RSpec/ContextWording:
   Exclude:
     - 'spec/suma/cli/export_spec.rb'
 
-# Offense count: 37
+# Offense count: 51
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
-  Max: 44
+  Max: 61
 
-# Offense count: 2
+# Offense count: 4
 # Configuration parameters: Max, AllowedIdentifiers, AllowedPatterns.
 RSpec/IndexedLet:
   Exclude:
+    - 'spec/suma/cli/compare_spec.rb'
     - 'spec/suma/cli/export_spec.rb'
 
-# Offense count: 33
+# Offense count: 22
+# Configuration parameters: AssignmentOnly.
+RSpec/InstanceVariable:
+  Exclude:
+    - 'spec/suma/cli/compare_spec.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+RSpec/IteratedExpectation:
+  Exclude:
+    - 'spec/suma/cli/compare_spec.rb'
+
+# Offense count: 1
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: have_received, receive
+RSpec/MessageSpies:
+  Exclude:
+    - 'spec/suma/cli/compare_spec.rb'
+
+# Offense count: 47
 RSpec/MultipleExpectations:
-  Max: 12
+  Max: 23
 
 # Offense count: 1
 # Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata.
@@ -154,12 +158,14 @@ RSpec/SpecFilePathFormat:
     - 'spec/suma/cli/expressir_spec.rb'
 
 # 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:
+RSpec/StubbedMock:
   Exclude:
-    - 'spec/suma/cli/export_spec.rb'
+    - 'spec/suma/cli/compare_spec.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: AllowedReceivers.
+# AllowedReceivers: Thread.current
+Style/HashEachMethods:
+  Exclude:
+    - 'spec/suma/cli/compare_spec.rb'

data/Gemfile

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

data/README.adoc

@@ -698,6 +698,125 @@ express-files/
 ----
 
 
+=== Compare schemas command
+
+==== General
+
+The `suma compare` command compares two EXPRESS schemas using eengine and
+generates an EXPRESS Changes YAML file tracking the differences.
+
+This command is essential for managing schema evolution across versions,
+particularly when working with multiple git branches of the same repository.
+
+[source,sh]
+----
+$ suma compare TRIAL_SCHEMA REFERENCE_SCHEMA --version VERSION [options]
+----
+
+Parameters:
+
+`TRIAL_SCHEMA`:: Path to the new/trial EXPRESS schema file
+`REFERENCE_SCHEMA`:: Path to the old/reference EXPRESS schema file
+
+Options:
+
+`--version=VERSION`, `-v VERSION`:: (required) Version number for this change version
+`--output=PATH`, `-o PATH`:: Output Change YAML file path (default: `{schema}.changes.yaml` in trial schema directory)
+`--mode=MODE`:: Schema comparison mode: `resource` or `module` (default: `resource`)
+`--trial-stepmod=PATH`:: Override auto-detected trial repository root
+`--reference-stepmod=PATH`:: Override auto-detected reference repository root
+`--verbose`:: Enable verbose output
+
+==== Typical workflow
+
+The compare command is designed for a two-repository workflow where you have
+different branches checked out:
+
+[source,sh]
+----
+# 1. Check out old version at /path/to/repo-old
+# 2. Check out new version at /path/to/repo-new
+# 3. Compare schemas:
+$ suma compare \
+    /path/to/repo-new/schemas/resources/action_schema/action_schema.exp \
+    /path/to/repo-old/schemas/resources/action_schema/action_schema.exp \
+    --version 2
+----
+
+==== Behavior
+
+The command:
+
+* Auto-detects git repository roots from schema file paths
+* Uses detected roots as stepmod paths for eengine
+* Generates or updates `.changes.yaml` file in the trial schema directory
+* **Replaces** existing change version if the version already exists
+* **Adds** new change version if the version is different
+
+==== Requirements
+
+This command requires `eengine` to be installed:
+
+* macOS: https://github.com/expresslang/homebrew-eengine
+* Linux: https://github.com/expresslang/eengine-releases
+
+[example]
+.To compare schemas with auto-detection
+[source,sh]
+----
+$ suma compare \
+    ~/iso-10303-new/schemas/resources/support_resource_schema/support_resource_schema.exp \
+    ~/iso-10303-old/schemas/resources/support_resource_schema/support_resource_schema.exp \
+    --version 2
+# => generates or updates support_resource_schema.changes.yaml
+----
+
+[example]
+.To compare with verbose output
+[source,sh]
+----
+$ suma compare schema_new.exp schema_old.exp --version 2 --verbose
+# Shows: eengine version, detected repo roots, XML generation, etc.
+----
+
+[example]
+.To specify custom output location
+[source,sh]
+----
+$ suma compare schema_new.exp schema_old.exp \
+    --version 2 \
+    --output /path/to/custom.changes.yaml
+----
+
+[example]
+.To override auto-detected repository roots
+[source,sh]
+----
+$ suma compare schema_new.exp schema_old.exp \
+    --version 2 \
+    --trial-stepmod ~/repo-new \
+    --reference-stepmod ~/repo-old
+----
+
+==== Generated Change YAML format
+
+The command generates EXPRESS Changes YAML files in the ISO 10303 format:
+
+[source,yaml]
+----
+---
+schema: support_resource_schema
+versions:
+- version: '2'
+  description: 'TYPE text: Underlying Type changed'
+  modifications:
+  - type: TYPE
+    name: text
+----
+
+For complete format documentation, see the
+https://www.expresslang.org/docs/express-changes[EXPRESS Changes specification].
+
 === Expressir command
 
 ==== General

data/lib/suma/cli/compare.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "../eengine/wrapper"
+require_relative "../eengine_converter"
+
+module Suma
+  module Cli
+    # Command to compare EXPRESS schemas using eengine
+    class Compare < Thor
+      desc "compare TRIAL_SCHEMA REFERENCE_SCHEMA",
+           "Compare EXPRESS schemas using eengine and generate Change YAML"
+      long_desc <<~DESC
+        Compare two EXPRESS schemas from different git branches/checkouts.
+
+        Typical workflow:
+          1. Check out old version of repo at /path/to/repo-old
+          2. Check out new version of repo at /path/to/repo-new
+          3. Run comparison:
+             suma compare \\
+               /path/to/repo-new/schemas/.../schema.exp \\
+               /path/to/repo-old/schemas/.../schema.exp \\
+               --version 2
+
+        The command will:
+          - Auto-detect repository roots from schema paths
+          - Use those as stepmod paths for eengine
+          - Generate/update the .changes.yaml file in the new repo
+      DESC
+
+      option :output, type: :string, aliases: "-o",
+                      desc: "Output Change YAML file path " \
+                            "(default: {schema}.changes.yaml in trial schema directory)"
+      option :version, type: :string, aliases: "-v", required: true,
+                       desc: "Version number for this change version"
+      option :mode, type: :string, default: "resource",
+                    enum: ["resource", "module"],
+                    desc: "Schema comparison mode"
+      option :trial_stepmod, type: :string,
+                             desc: "Override auto-detected trial repo root"
+      option :reference_stepmod, type: :string,
+                                 desc: "Override auto-detected reference repo root"
+      option :verbose, type: :boolean, default: false,
+                       desc: "Enable verbose output"
+
+      def compare(trial_schema, reference_schema)
+        # Validate schema files exist
+        unless File.exist?(trial_schema)
+          say "Error: Trial schema not found: #{trial_schema}", :red
+          exit 1
+        end
+
+        unless File.exist?(reference_schema)
+          say "Error: Reference schema not found: #{reference_schema}", :red
+          exit 1
+        end
+
+        # Check eengine availability
+        unless Eengine::Wrapper.available?
+          say "Error: eengine not found in PATH", :red
+          say "Install eengine following instructions at:"
+          say "  macOS: https://github.com/expresslang/homebrew-eengine"
+          say "  Linux: https://github.com/expresslang/eengine-releases"
+          exit 1
+        end
+
+        # Auto-detect repo roots
+        trial_stepmod = options[:trial_stepmod] ||
+          detect_repo_root(trial_schema)
+        reference_stepmod = options[:reference_stepmod] ||
+          detect_repo_root(reference_schema)
+
+        if options[:verbose]
+          say "Using eengine version: #{Eengine::Wrapper.version}", :green
+          say "Trial repo root: #{trial_stepmod}", :cyan
+          say "Reference repo root: #{reference_stepmod}", :cyan
+        end
+
+        # Create a temporary directory for eengine output
+        require "tmpdir"
+        out_dir = nil
+        out_dir = Dir.mktmpdir("eengine-compare-")
+
+        # Run comparison
+        result = Eengine::Wrapper.compare(
+          trial_schema,
+          reference_schema,
+          mode: options[:mode],
+          trial_stepmod: trial_stepmod,
+          reference_stepmod: reference_stepmod,
+          out_dir: out_dir,
+        )
+
+        unless result[:has_changes]
+          say "No changes detected between schemas", :yellow
+          # Clean up temp directory
+          FileUtils.rm_rf(out_dir) if out_dir && File.directory?(out_dir)
+          return
+        end
+
+        unless result[:xml_path]
+          say "Error: XML output not found", :red
+          exit 1
+        end
+
+        if options[:verbose]
+          say "Comparison XML generated: #{result[:xml_path]}", :green
+        end
+
+        # Convert to Change YAML
+        convert_to_change_yaml(result[:xml_path], trial_schema, out_dir)
+      rescue Eengine::EengineError => e
+        # Clean up temp directory
+        FileUtils.rm_rf(out_dir) if out_dir && File.directory?(out_dir)
+        say "Error: #{e.message}", :red
+        say e.stderr if e.respond_to?(:stderr) && options[:verbose]
+        exit 1
+      end
+
+      private
+
+      def detect_repo_root(schema_path)
+        # Walk up from schema path to find .git directory
+        current = File.expand_path(File.dirname(schema_path))
+
+        loop do
+          if File.directory?(File.join(current, ".git"))
+            return current
+          end
+
+          parent = File.dirname(current)
+          break if parent == current # reached root
+
+          current = parent
+        end
+
+        # If no .git found, use the directory containing the schema
+        # (for non-git workflows)
+        File.dirname(schema_path)
+      end
+
+      def convert_to_change_yaml(xml_path, trial_schema, out_dir)
+        schema_name = extract_schema_name(trial_schema)
+        output_path = determine_output_path(trial_schema)
+
+        # Load existing ChangeSchema if it exists
+        existing_schema = if File.exist?(output_path)
+                            if options[:verbose]
+                              say "Loading existing change schema: " \
+                                  "#{output_path}", :cyan
+                            end
+                            require "expressir/changes"
+                            Expressir::Changes::SchemaChange.from_file(output_path)
+                          end
+
+        # Convert using Suma's converter
+        converter = EengineConverter.new(xml_path, schema_name)
+        change_schema = converter.convert(
+          version: options[:version],
+          existing_change_schema: existing_schema,
+        )
+
+        # Save using Expressir model
+        change_schema.to_file(output_path)
+
+        # Determine what action was taken
+        if existing_schema
+          existing_version = existing_schema.versions.find do |ed|
+            ed.version == options[:version]
+          end
+
+          say "Change YAML file updated: #{output_path}", :green
+          if existing_version
+            say "  Replaced existing version #{options[:version]}", :green
+          else
+            say "  Added version #{options[:version]} to change versions",
+                :green
+          end
+        else
+          say "Change YAML file created: #{output_path}", :green
+        end
+
+        if options[:verbose]
+          say "\nGenerated change schema content:", :cyan
+          say File.read(output_path)
+        end
+
+        # Clean up temp directory and XML file
+        FileUtils.rm_rf(out_dir) if out_dir && File.directory?(out_dir)
+      end
+
+      def extract_schema_name(path)
+        # Remove version suffix if present (e.g., schema_1.exp -> schema)
+        basename = File.basename(path, ".exp")
+        basename.sub(/_\d+$/, "")
+      end
+
+      def determine_output_path(trial_schema)
+        if options[:output]
+          options[:output]
+        else
+          # Place .changes.yaml next to the trial schema in the NEW repo
+          base = extract_schema_name(trial_schema)
+          dir = File.dirname(trial_schema)
+          File.join(dir, "#{base}.changes.yaml")
+        end
+      end
+    end
+  end
+end

data/lib/suma/cli/export.rb

@@ -2,6 +2,7 @@
 
 require "thor"
 require_relative "../thor_ext"
+require_relative "../export_standalone_schema"
 
 module Suma
   module Cli
@@ -86,22 +87,12 @@ module Suma
       def create_schema_from_exp_file(exp_file)
         # Create a schema object from a standalone EXPRESS file
         # The id will be determined during parsing
-        StandaloneSchema.new(
+        ExportStandaloneSchema.new(
           id: nil,
           path: File.expand_path(exp_file),
         )
       end
 
-      # Simple schema class for standalone EXPRESS files
-      class StandaloneSchema
-        attr_accessor :id, :path
-
-        def initialize(id:, path:)
-          @id = id
-          @path = path
-        end
-      end
-
       def self.exit_on_failure?
         true
       end

data/lib/suma/cli.rb

@@ -74,6 +74,25 @@ module Suma
         Cli::Export.start
       end
 
+      desc "compare TRIAL_SCHEMA REFERENCE_SCHEMA",
+           "Compare EXPRESS schemas using eengine and generate Change YAML"
+      option :output, type: :string, aliases: "-o",
+                      desc: "Output Change YAML file path"
+      option :version, type: :string, aliases: "-v", required: true,
+                       desc: "Version number for this change version"
+      option :mode, type: :string, default: "resource",
+                    desc: "Schema comparison mode (resource/module)"
+      option :trial_stepmod, type: :string,
+                             desc: "Override auto-detected trial repo root"
+      option :reference_stepmod, type: :string,
+                                 desc: "Override auto-detected reference repo root"
+      option :verbose, type: :boolean, default: false,
+                       desc: "Enable verbose output"
+      def compare(_trial_schema, _reference_schema)
+        require_relative "cli/compare"
+        Cli::Compare.start
+      end
+
       desc "validate SUBCOMMAND ...ARGS", "Validate express documents"
       subcommand "validate", Cli::Validate
 

data/lib/suma/eengine/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Suma
+  module Eengine
+    # Base error class for eengine-related errors
+    class EengineError < StandardError; end
+
+    # Raised when eengine binary is not found in PATH
+    class EengineNotFoundError < EengineError
+      def initialize
+        super("eengine not found in PATH. Install eengine:\n  " \
+              "macOS: https://github.com/expresslang/homebrew-eengine\n  " \
+              "Linux: https://github.com/expresslang/eengine-releases")
+      end
+    end
+
+    # Raised when eengine comparison fails
+    class ComparisonError < EengineError
+      attr_reader :stderr
+
+      def initialize(message, stderr = nil)
+        super(message)
+        @stderr = stderr
+      end
+    end
+  end
+end

data/lib/suma/eengine/wrapper.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "errors"
+
+module Suma
+  module Eengine
+    # Wrapper for eengine binary to compare EXPRESS schemas
+    class Wrapper
+      class << self
+        # Compare two EXPRESS schemas using eengine
+        #
+        # @param trial_schema [String] Path to the new/trial schema
+        # @param reference_schema [String] Path to the old/reference schema
+        # @param options [Hash] Comparison options
+        # @option options [String] :mode Comparison mode (resource/module)
+        # @option options [String] :trial_stepmod Path to trial repo root
+        # @option options [String] :reference_stepmod Path to reference repo root
+        # @return [Hash] Result with :success, :xml_path, :has_changes, :output
+        def compare(trial_schema, reference_schema, options = {})
+          ensure_eengine_available!
+
+          cmd = build_command(trial_schema, reference_schema, options)
+          output, error, status = Open3.capture3(*cmd)
+
+          unless status.success?
+            error_message = error.empty? ? "Unknown eengine error" : error.strip
+            raise ComparisonError.new(error_message, error)
+          end
+
+          parse_output(output, options)
+        end
+
+        # Check if eengine is available on the system
+        #
+        # @return [Boolean] true if eengine binary is found
+        def available?
+          return false if ENV["EENGINE_DISABLED"] == "true"
+
+          eengine_path && eengine_executable?
+        end
+
+        # Get the eengine version
+        #
+        # @return [String, nil] Version string or nil if unavailable
+        def version
+          return nil unless available?
+
+          cmd = [eengine_path, "--version"]
+          output, _, status = Open3.capture3(*cmd)
+          status.success? ? parse_version(output) : nil
+        rescue StandardError
+          nil
+        end
+
+        private
+
+        def eengine_path
+          @eengine_path ||= find_eengine_binary
+        end
+
+        def find_eengine_binary
+          # Search for eengine or eengine-* in PATH
+          ENV["PATH"].split(File::PATH_SEPARATOR).each do |dir|
+            # First try plain eengine
+            plain_path = File.join(dir, "eengine")
+            return plain_path if File.exist?(plain_path) && File.executable?(plain_path)
+
+            # Then try eengine-* pattern
+            Dir.glob(File.join(dir, "eengine-*")).each do |path|
+              return path if File.executable?(path)
+            end
+          end
+          nil
+        end
+
+        def eengine_executable?
+          eengine_path && File.executable?(eengine_path)
+        end
+
+        def ensure_eengine_available!
+          raise EengineNotFoundError unless available?
+        end
+
+        def build_command(trial, reference, options)
+          cmd = [
+            eengine_path,
+            "--compare",
+            "-trial_schema", trial,
+            "-trial_stepmod", options[:trial_stepmod] || ".",
+            "-reference_schema", reference,
+            "-reference_stepmod", options[:reference_stepmod] || ".",
+            "-mode", options[:mode] || "resource",
+            "--xml-output"
+          ]
+
+          # Add output directory if specified
+          if options[:out_dir]
+            cmd += ["-out-dir", options[:out_dir]]
+          end
+
+          cmd
+        end
+
+        def parse_output(output, _options)
+          # Extract XML file path from output
+          # eengine prints: "Writing \"path/to/file.xml\""
+          xml_match = output.match(/Writing "(.+\.xml)"/)
+          xml_path = xml_match ? xml_match[1] : nil
+
+          # Expand to absolute path if found
+          xml_path = File.expand_path(xml_path) if xml_path
+
+          # Determine if changes were detected
+          has_changes = detect_changes(output)
+
+          {
+            success: true,
+            xml_path: xml_path,
+            has_changes: has_changes,
+            output: output,
+          }
+        end
+
+        def detect_changes(output)
+          # Check for various indicators of changes in the output
+          return true if output.include?("Comparing TYPE")
+          return true if output.include?("Comparing ENTITY")
+          return true if output.include?("Comparing FUNCTION")
+          return true if output.include?("Comparing RULE")
+          return true if output.include?("Comparing PROCEDURE")
+
+          # Check for modification indicators
+          return true if output.include?("changed")
+          return true if output.include?("modified")
+          return true if output.include?("added")
+          return true if output.include?("removed")
+
+          false
+        end
+
+        def parse_version(output)
+          # Extract version from output like "Express Engine 5.2.7"
+          version_match = output.match(/Express Engine ([\d.]+)/)
+          version_match ? version_match[1] : nil
+        end
+      end
+    end
+  end
+end

data/lib/suma/eengine_converter.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "expressir/commands/changes_import_eengine"
+
+module Suma
+  # Converts eengine comparison XML to Expressir::Changes::SchemaChange
+  # This is a thin wrapper around Expressir's ChangesImportEengine command
+  class EengineConverter
+    def initialize(xml_path, schema_name)
+      @xml_path = xml_path
+      @schema_name = schema_name
+      @xml_content = File.read(xml_path)
+    end
+
+    # Convert the eengine XML to a ChangeSchema
+    #
+    # @param version [String] Version number for this change version
+    # @param existing_change_schema [Expressir::Changes::SchemaChange, nil]
+    #   Existing schema to append to, or nil to create new
+    # @return [Expressir::Changes::SchemaChange] The updated change schema
+    def convert(version:, existing_change_schema: nil)
+      # Use Expressir's built-in conversion which properly handles
+      # HTML elements in descriptions
+      Expressir::Commands::ChangesImportEengine.from_xml(
+        @xml_content,
+        @schema_name,
+        version,
+        existing_schema: existing_change_schema,
+      )
+    end
+  end
+end

data/lib/suma/export_standalone_schema.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Suma
+  # Simple schema class for standalone EXPRESS files
+  # Used when exporting individual .exp files that are not part of a manifest
+  class ExportStandaloneSchema
+    attr_accessor :id, :path
+
+    def initialize(id:, path:)
+      @id = id
+      @path = path
+    end
+  end
+end

data/lib/suma/schema_exporter.rb

@@ -2,6 +2,7 @@
 
 require_relative "express_schema"
 require_relative "utils"
+require_relative "export_standalone_schema"
 require "fileutils"
 
 module Suma
@@ -44,7 +45,7 @@ module Suma
     def export_single_schema(schema)
       # Check if this is a standalone EXPRESS file
       # (not from a manifest structure)
-      is_standalone_file = schema.is_a?(Cli::Export::StandaloneSchema)
+      is_standalone_file = schema.is_a?(ExportStandaloneSchema)
       schema_output_path = determine_output_path(schema, is_standalone_file)
 
       express_schema = ExpressSchema.new(

data/lib/suma/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Suma
-  VERSION = "0.1.24"
+  VERSION = "0.1.26"
 end

data/suma.gemspec

@@ -33,7 +33,7 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "expressir", "~> 2.1"
+  spec.add_dependency "expressir", ">= 2.1.29", "~> 2.1"
   spec.add_dependency "glossarist", "~> 2.3.7"
   spec.add_dependency "lutaml-model", "~> 0.7"
   spec.add_dependency "metanorma-cli"

metadata

@@ -1,19 +1,22 @@
 --- !ruby/object:Gem::Specification
 name: suma
 version: !ruby/object:Gem::Version
-  version: 0.1.24
+  version: 0.1.26
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-12 00:00:00.000000000 Z
+date: 2025-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: expressir
   requirement: !ruby/object:Gem::Requirement
     requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.1.29
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
@@ -21,6 +24,9 @@ dependencies:
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.1.29
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
@@ -162,6 +168,7 @@ files:
 - lib/suma.rb
 - lib/suma/cli.rb
 - lib/suma/cli/build.rb
+- lib/suma/cli/compare.rb
 - lib/suma/cli/convert_jsdai.rb
 - lib/suma/cli/export.rb
 - lib/suma/cli/extract_terms.rb
@@ -172,6 +179,10 @@ files:
 - lib/suma/cli/validate_links.rb
 - lib/suma/collection_config.rb
 - lib/suma/collection_manifest.rb
+- lib/suma/eengine/errors.rb
+- lib/suma/eengine/wrapper.rb
+- lib/suma/eengine_converter.rb
+- lib/suma/export_standalone_schema.rb
 - lib/suma/express_schema.rb
 - lib/suma/jsdai.rb
 - lib/suma/jsdai/figure.rb