suma 0.1.23 → 0.1.25

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 edition"
+      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_edition = existing_schema.editions.find do |ed|
+            ed.version == options[:version]
+          end
+
+          say "Change YAML file updated: #{output_path}", :green
+          if existing_edition
+            say "  Replaced existing version #{options[:version]}", :green
+          else
+            say "  Added version #{options[:version]} to change editions",
+                :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,42 +2,50 @@
 
 require "thor"
 require_relative "../thor_ext"
+require_relative "../export_standalone_schema"
 
 module Suma
   module Cli
     # Export command for exporting EXPRESS schemas from a manifest
     class Export < Thor
-      desc "export MANIFEST_FILE",
-           "Export EXPRESS schemas from manifest"
+      desc "export *FILES",
+           "Export EXPRESS schemas from manifest files or " \
+           "standalone EXPRESS files"
       option :output, type: :string, aliases: "-o", required: true,
                       desc: "Output directory path"
-      option :additional, type: :array, aliases: "-a",
-                          desc: "Additional schemas manifest files to merge (can be specified multiple times)"
       option :annotations, type: :boolean, default: false,
                            desc: "Include annotations (remarks/comments)"
       option :zip, type: :boolean, default: false,
                    desc: "Create ZIP archive of exported schemas"
 
-      def export(manifest_file)
+      def export(*files)
         require_relative "../schema_exporter"
         require_relative "../utils"
         require "expressir"
 
-        unless File.exist?(manifest_file)
-          raise Errno::ENOENT, "Specified manifest file " \
-                               "`#{manifest_file}` not found."
-        end
-
-        run(manifest_file, options)
+        validate_files(files)
+        run(files, options)
       end
 
       private
 
-      def run(manifest_file, options)
-        config = load_and_merge_configs(manifest_file, options[:additional])
+      def validate_files(files)
+        if files.empty?
+          raise ArgumentError, "At least one file must be specified"
+        end
+
+        files.each do |file|
+          unless File.exist?(file)
+            raise Errno::ENOENT, "Specified file `#{file}` not found."
+          end
+        end
+      end
+
+      def run(files, options)
+        schemas = load_schemas_from_files(files)
 
         exporter = SchemaExporter.new(
-          config: config,
+          schemas: schemas,
           output_path: options[:output],
           options: {
             annotations: options[:annotations],
@@ -48,36 +56,40 @@ module Suma
         exporter.export
       end
 
-      # rubocop:disable Metrics/MethodLength
-      def load_and_merge_configs(primary_path, additional_paths)
-        primary_config = Expressir::SchemaManifest.from_file(primary_path)
-        return primary_config unless additional_paths && !additional_paths.empty?
+      def load_schemas_from_files(files)
+        all_schemas = []
 
-        # Load all additional manifests
-        additional_configs = additional_paths.map do |path|
-          unless File.exist?(path)
-            raise Errno::ENOENT, "Specified additional manifest file " \
-                                 "`#{path}` not found."
-          end
-          Expressir::SchemaManifest.from_file(path)
+        files.each do |file|
+          all_schemas += process_file(file)
         end
 
-        # Merge all configs into the primary
-        merge_all_configs(primary_config, additional_configs)
+        all_schemas
       end
-      # rubocop:enable Metrics/MethodLength
-
-      def merge_all_configs(primary, additional_configs)
-        # Collect all schemas from primary and all additional manifests
-        all_schemas = primary.schemas.dup
 
-        additional_configs.each do |config|
-          all_schemas += config.schemas
+      def process_file(file)
+        case File.extname(file).downcase
+        when ".yml", ".yaml"
+          load_manifest_schemas(file)
+        when ".exp"
+          [create_schema_from_exp_file(file)]
+        else
+          raise ArgumentError, "Unsupported file type: #{file}. " \
+                               "Only .yml, .yaml, and .exp files are " \
+                               "supported."
         end
+      end
+
+      def load_manifest_schemas(file)
+        manifest = Expressir::SchemaManifest.from_file(file)
+        manifest.schemas
+      end
 
-        Expressir::SchemaManifest.new(
-          path: primary.path,
-          schemas: all_schemas,
+      def create_schema_from_exp_file(exp_file)
+        # Create a schema object from a standalone EXPRESS file
+        # The id will be determined during parsing
+        ExportStandaloneSchema.new(
+          id: nil,
+          path: File.expand_path(exp_file),
         )
       end
 

data/lib/suma/cli.rb

@@ -3,6 +3,7 @@
 require "thor"
 require_relative "thor_ext"
 require_relative "cli/validate"
+require "expressir/cli"
 
 module Suma
   module Cli
@@ -15,10 +16,9 @@ module Suma
       option :compile, type: :boolean, default: true,
                        desc: "Compile or skip compile of collection"
       option :schemas_all_path, type: :string, aliases: "-s",
-                                desc: "Generate file that contains all schemas in the collection."
+                                desc: "Generate file that contains all " \
+                                      "schemas in the collection."
       def build(_site_manifest)
-        # # If no arguments, add an empty array to ensure the default command is triggered
-        # args = [] if args.empty?
         require_relative "cli/build"
         Cli::Build.start
       end
@@ -60,24 +60,45 @@ module Suma
         Cli::ConvertJsdai.start
       end
 
-      desc "export MANIFEST_FILE",
-           "Export EXPRESS schemas from manifest"
+      desc "export *FILES",
+           "Export EXPRESS schemas from manifest files or " \
+           "standalone EXPRESS files"
       option :output, type: :string, aliases: "-o", required: true,
                       desc: "Output directory path"
-      option :additional, type: :array, aliases: "-a",
-                          desc: "Additional schemas manifest files to merge (can be specified multiple times)"
       option :annotations, type: :boolean, default: false,
                            desc: "Include annotations (remarks/comments)"
       option :zip, type: :boolean, default: false,
                    desc: "Create ZIP archive of exported schemas"
-      def export(_manifest_file)
+      def export(*_files)
         require_relative "cli/export"
         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 edition"
+      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
 
+      desc "expressir SUBCOMMAND ...ARGS", "Expressir commands"
+      subcommand "expressir", Expressir::Cli
+
       def self.exit_on_failure?
         true
       end

data/lib/suma/collection_manifest.rb

@@ -36,12 +36,25 @@ module Suma
       model.entry = CollectionManifest.from_yaml(value.to_yaml)
     end
 
+    # Recursively exports schema configuration by traversing collection manifests.
+    #
+    # This method builds an EXPRESS Schema Manifest (Expressir::SchemaManifest) by:
+    # 1. Starting with an empty or existing Expressir::SchemaManifest
+    # 2. Recursively traversing child entries to collect schemas
+    # 3. Using Expressir::SchemaManifest#concat to combine manifests
+    #
+    # The actual schema manifest operations (creation, concatenation, serialization)
+    # are handled by Expressir's SchemaManifest class, keeping the logic DRY.
+    #
+    # @param path [String] Base path for resolving relative schema paths
+    # @return [Expressir::SchemaManifest] Combined schema manifest
     def export_schema_config(path)
       export_config = @schema_config || Expressir::SchemaManifest.new
       return export_config unless entry
 
       entry.each do |x|
         child_config = x.export_schema_config(path)
+        # Use Expressir's concat method to combine schema manifests
         export_config.concat(child_config) if child_config
       end
 

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 edition
+    # @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