expressir 2.1.15 → 2.1.16

data/lib/expressir/benchmark.rb

@@ -0,0 +1,307 @@
+module Expressir
+  module Benchmark
+    require "benchmark"
+    require "json"
+    require "csv"
+
+    class << self
+      # Measures the execution time of schema loading and optionally reports it
+      # @param file [String] File being processed
+      # @param options [Hash] Options for benchmarking
+      # @return The result of the block
+      def measure_file(file)
+        return yield unless Expressir.configuration.benchmark_enabled?
+
+        if Expressir.configuration.benchmark_ips?
+          require "benchmark/ips"
+
+          result = nil
+          ::Benchmark.ips do |x|
+            x.config(time: Expressir.configuration.benchmark_iterations,
+                     warmup: Expressir.configuration.benchmark_warmup)
+
+            x.report("Loading #{file}") do
+              result = yield
+            end
+
+            if Expressir.configuration.benchmark_save?
+              x.save! "expressir_benchmark_#{File.basename(file)}"
+            end
+          end
+
+          # Calculate objects per second
+          if result.respond_to?(:schemas)
+            objects_per_second = calculate_objects_per_second(result)
+            puts "Objects per second: #{objects_per_second}" if Expressir.configuration.benchmark_verbose?
+          end
+
+        else
+          # Standard benchmarking
+          result = nil
+          time = ::Benchmark.measure do
+            result = yield
+          end
+
+          if result.respond_to?(:schemas)
+            objects_per_second = calculate_objects_per_second(result, time.real)
+            output_benchmark_result(file, time.real, objects_per_second)
+          else
+            output_benchmark_result(file, time.real)
+          end
+
+        end
+        result
+      end
+
+      # Benchmarks file collection processing
+      # @param files [Array<String>] List of files to process
+      # @return [Array] Results from processing files
+      def measure_collection(files)
+        unless Expressir.configuration.benchmark_enabled?
+          # Process each file individually even when benchmarking is disabled
+          results = []
+          files.each do |file|
+            file_results = yield(file)
+            results.concat(Array(file_results))
+          end
+          return results
+        end
+
+        results = []
+        total_time = ::Benchmark.measure do
+          files.each_with_index do |file, i|
+            if Expressir.configuration.benchmark_verbose?
+              puts "#{i + 1}/#{files.length} Processing #{file}"
+            end
+
+            file_results = measure_file(file) do
+              yield(file)
+            end
+
+            results.concat(Array(file_results))
+          end
+        end
+
+        output_collection_result(files.length, total_time.real, results)
+        results
+      end
+
+      # Measures reference resolution
+      # @return The result of the block
+      def measure_references
+        return yield unless Expressir.configuration.benchmark_enabled?
+
+        if Expressir.configuration.benchmark_ips?
+          require "benchmark/ips"
+
+          result = nil
+          ::Benchmark.ips do |x|
+            x.config(time: Expressir.configuration.benchmark_iterations,
+                     warmup: Expressir.configuration.benchmark_warmup)
+
+            x.report("Reference resolution") do
+              result = yield
+            end
+          end
+
+        else
+          result = nil
+          time = ::Benchmark.measure do
+            result = yield
+          end
+
+          output_benchmark_result("Reference resolution", time.real)
+        end
+        result
+      end
+
+      # Benchmark with caching
+      # @param path [String] Path to the file
+      # @param cache_path [String] Path for the cache file
+      # @return [Hash] Results with timing information
+      def measure_with_cache(path, cache_path = nil)
+        return yield(path) unless Expressir.configuration.benchmark_enabled?
+
+        require "tempfile"
+        temp_file = nil
+
+        unless cache_path
+          temp_file = Tempfile.new(["expressir_cache", ".bin"])
+          cache_path = temp_file.path
+        end
+
+        results = {}
+
+        # Measure parsing time
+        parsing_time = ::Benchmark.measure do
+          results[:repository] = yield(path)
+        end
+        results[:parsing_time] = parsing_time.real
+
+        # Measure cache writing time
+        cache_write_time = ::Benchmark.measure do
+          Expressir::Express::Cache.to_file(cache_path, results[:repository])
+        end
+        results[:cache_write_time] = cache_write_time.real
+
+        # Measure cache reading time
+        cache_read_time = ::Benchmark.measure do
+          results[:cached_repository] = Expressir::Express::Cache.from_file(cache_path)
+        end
+        results[:cache_read_time] = cache_read_time.real
+
+        # Output results
+        if Expressir.configuration.benchmark_verbose?
+          puts "Parsing time:      #{results[:parsing_time].round(4)}s"
+          puts "Cache write time:  #{results[:cache_write_time].round(4)}s"
+          puts "Cache read time:   #{results[:cache_read_time].round(4)}s"
+
+          if results[:repository].respond_to?(:schemas)
+            objects = count_objects(results[:repository])
+            puts "Total objects:     #{objects}"
+            puts "Objects per second (parsing): #{(objects / results[:parsing_time]).round(2)}"
+            puts "Objects per second (reading): #{(objects / results[:cache_read_time]).round(2)}"
+          end
+        end
+
+        # Clean up temp file if we created one
+        if temp_file
+          temp_file.close
+          temp_file.unlink
+        end
+
+        results
+      end
+
+      private
+
+      # Calculate objects per second
+      # @param repository [Object] The repository object
+      # @param time [Float] The time taken in seconds
+      # @return [Float] Objects per second
+      def calculate_objects_per_second(repository, time = 1.0)
+        objects = count_objects(repository)
+        (objects / time).round(2)
+      end
+
+      # Count objects in a repository
+      # @param repository [Object] The repository object
+      # @return [Integer] Number of objects
+      def count_objects(repository)
+        return 0 unless repository.respond_to?(:schemas)
+
+        count = repository.schemas.size
+
+        repository.schemas.each do |schema|
+          count += schema.entities.size if schema.entities
+          count += schema.types.size if schema.types
+          count += schema.functions.size if schema.functions
+          count += schema.rules.size if schema.rules
+          count += schema.procedures.size if schema.procedures
+          count += schema.constants.size if schema.constants
+
+          # Count attributes in entities
+          schema.entities&.each do |entity|
+            # Count explicit attributes
+            if entity.attributes
+              count += entity.attributes.size
+            end
+
+            # Count inheritance relationships
+            count += 1 if entity.subtype_of
+          end
+        end
+
+        count
+      end
+
+      # Output benchmark result in the appropriate format
+      # @param label [String] Label for the benchmark
+      # @param time [Float] Time in seconds
+      # @param objects_per_second [Float, nil] Objects per second metric (optional)
+      def output_benchmark_result(label, time, objects_per_second = nil)
+        time_rounded = time.round(4)
+
+        case Expressir.configuration.benchmark_format
+        when "json"
+          result = {
+            label: label,
+            time_seconds: time_rounded,
+          }
+          result[:objects_per_second] = objects_per_second if objects_per_second
+          puts JSON.generate(result)
+        when "csv"
+          headers = ["Label", "Time (s)"]
+          headers << "Objects/s" if objects_per_second
+
+          values = [label, time_rounded]
+          values << objects_per_second if objects_per_second
+
+          puts headers.join(",")
+          puts values.join(",")
+        else
+          # Default format
+          message = "#{label}: #{time_rounded}s"
+          message += " (#{objects_per_second} objects/s)" if objects_per_second
+          puts message if Expressir.configuration.benchmark_verbose?
+        end
+      end
+
+      # Output collection benchmark result
+      # @param count [Integer] Number of files processed
+      # @param total_time [Float] Total time in seconds
+      # @param results [Array] Array of results
+      def output_collection_result(count, total_time, results)
+        avg_time = total_time / count
+
+        # Get total object count if possible
+        total_objects = 0
+        schema_count = 0
+
+        # Try to count total objects and schemas
+        results.each do |result|
+          if result.respond_to?(:schemas)
+            schema_count += result.schemas.size
+            total_objects += count_objects(result)
+          elsif result.is_a?(Array)
+            result.each do |r|
+              if r.respond_to?(:id)  # Likely a schema
+                schema_count += 1
+                total_objects += 1   # Count the schema itself
+              end
+            end
+          end
+        end
+
+        objects_per_second = (total_objects / total_time).round(2)
+
+        case Expressir.configuration.benchmark_format
+        when "json"
+          result = {
+            files_processed: count,
+            schemas_loaded: schema_count,
+            total_objects: total_objects,
+            total_time_seconds: total_time.round(4),
+            average_time_seconds: avg_time.round(4),
+            objects_per_second: objects_per_second,
+          }
+          puts JSON.generate(result)
+        when "csv"
+          headers = ["Files", "Schemas", "Objects", "Total Time (s)", "Avg Time (s)", "Objects/s"]
+          values = [count, schema_count, total_objects, total_time.round(4), avg_time.round(4), objects_per_second]
+
+          puts headers.join(",")
+          puts values.join(",")
+        else
+          # Default format
+          if Expressir.configuration.benchmark_verbose?
+            puts "\nProcessed #{count} files in #{total_time.round(4)}s"
+            puts "Loaded #{schema_count} schemas containing #{total_objects} objects"
+            puts "Average time per file: #{avg_time.round(4)}s"
+            puts "Performance: #{objects_per_second} objects/s"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/expressir/cli.rb

@@ -1,4 +1,5 @@
 require "thor"
+require "yaml"
 
 module Expressir
   class Cli < Thor
@@ -11,6 +12,67 @@ module Expressir
       end
     end
 
+    desc "clean PATH", "Strip remarks and prettify EXPRESS schema at PATH"
+    method_option :output, type: :string, desc: "Output file path (defaults to stdout)"
+    def clean(path)
+      repository = Expressir::Express::Parser.from_file(path)
+      formatted_schemas = repository.schemas.map do |schema|
+        # Format schema without remarks
+        schema.to_s(no_remarks: true)
+      end.join("\n\n")
+
+      if options[:output]
+        File.write(options[:output], formatted_schemas)
+        puts "Cleaned schema written to #{options[:output]}"
+      else
+        puts formatted_schemas
+      end
+    end
+
+    desc "benchmark FILE_OR_YAML", "Benchmark schema loading performance for a file or list of files from YAML"
+    method_option :ips, type: :boolean, desc: "Use benchmark-ips for detailed statistics"
+    method_option :verbose, type: :boolean, desc: "Show verbose output"
+    method_option :save, type: :boolean, desc: "Save benchmark results to file"
+    method_option :format, type: :string, desc: "Output format (json, csv, default)"
+    def benchmark(path)
+      # Enable benchmarking via configuration
+      Expressir.configuration.benchmark_enabled = true
+      Expressir.configuration.benchmark_ips = options[:ips]
+      Expressir.configuration.benchmark_verbose = options[:verbose]
+      Expressir.configuration.benchmark_save = options[:save]
+      Expressir.configuration.benchmark_format = options[:format] if options[:format]
+
+      if [".yml", ".yaml"].include?(File.extname(path).downcase)
+        benchmark_from_yaml(path)
+      else
+        benchmark_file(path)
+      end
+    end
+
+    desc "benchmark-cache FILE_OR_YAML", "Benchmark schema loading with caching"
+    method_option :ips, type: :boolean, desc: "Use benchmark-ips for detailed statistics"
+    method_option :verbose, type: :boolean, desc: "Show verbose output"
+    method_option :save, type: :boolean, desc: "Save benchmark results to file"
+    method_option :format, type: :string, desc: "Output format (json, csv, default)"
+    method_option :cache_path, type: :string, desc: "Path to store the cache file"
+    def benchmark_cache(path)
+      # Same options as benchmark + cache_path
+      Expressir.configuration.benchmark_enabled = true
+      Expressir.configuration.benchmark_ips = options[:ips]
+      Expressir.configuration.benchmark_verbose = options[:verbose]
+      Expressir.configuration.benchmark_save = options[:save]
+      Expressir.configuration.benchmark_format = options[:format] if options[:format]
+
+      # Run benchmarks with cache
+      cache_path = options[:cache_path] || generate_temp_cache_path
+
+      if [".yml", ".yaml"].include?(File.extname(path).downcase)
+        benchmark_cache_from_yaml(path, cache_path)
+      else
+        benchmark_cache_file(path, cache_path)
+      end
+    end
+
     no_commands do
       def _validate_schema(path)
         repository = Expressir::Express::Parser.from_file(path)
@@ -30,6 +92,109 @@ module Expressir
           puts msg
         end
       end
+
+      def benchmark_file(path)
+        puts "Express Schema Loading Benchmark"
+        puts "--------------------------------"
+
+        repository = Expressir::Benchmark.measure_file(path) do
+          Expressir::Express::Parser.from_file(path)
+        end
+
+        if repository
+          puts "Loaded #{repository.schemas.size} schemas"
+        else
+          puts "Failed to load schema"
+        end
+      end
+
+      def benchmark_from_yaml(yaml_path)
+        puts "Express Schema Loading Benchmark from YAML"
+        puts "--------------------------------"
+
+        # Load schema list from YAML
+        schema_list = YAML.load_file(yaml_path)
+        if schema_list.is_a?(Hash) && schema_list["schemas"]
+          # Handle format: { "schemas": ["path1", "path2", ...] }
+          schema_files = schema_list["schemas"]
+        elsif schema_list.is_a?(Array)
+          # Handle format: ["path1", "path2", ...]
+          schema_files = schema_list
+        else
+          puts "Invalid YAML format. Expected an array of schema paths or a hash with a 'schemas' key."
+          return
+        end
+
+        puts "YAML File: #{yaml_path}"
+        puts "Number of schemas in list: #{schema_files.size}"
+        puts "--------------------------------"
+
+        # Load the schemas
+        Expressir::Benchmark.measure_collection(schema_files) do |file|
+          repository = Expressir::Express::Parser.from_file(file)
+          repository.schemas
+        end
+      end
+
+      def benchmark_cache_file(path, cache_path)
+        puts "Express Schema Loading Benchmark with Caching"
+        puts "--------------------------------"
+        puts "Schema: #{path}"
+        puts "Cache: #{cache_path}"
+        puts "--------------------------------"
+
+        # Benchmark with caching
+        results = Expressir::Benchmark.measure_with_cache(path, cache_path) do |file|
+          Expressir::Express::Parser.from_file(file)
+        end
+
+        if results[:repository]
+          schema_count = results[:repository].schemas.size
+          puts "Loaded #{schema_count} schemas"
+        else
+          puts "Failed to load schema"
+        end
+      end
+
+      def benchmark_cache_from_yaml(yaml_path, cache_path)
+        puts "Express Schema Loading Benchmark with Caching from YAML"
+        puts "--------------------------------"
+
+        # Load schema list from YAML
+        schema_list = YAML.load_file(yaml_path)
+        if schema_list.is_a?(Hash) && schema_list["schemas"]
+          # Handle format: { "schemas": ["path1", "path2", ...] }
+          schema_files = schema_list["schemas"]
+        elsif schema_list.is_a?(Array)
+          # Handle format: ["path1", "path2", ...]
+          schema_files = schema_list
+        else
+          puts "Invalid YAML format. Expected an array of schema paths or a hash with a 'schemas' key."
+          return
+        end
+
+        puts "YAML File: #{yaml_path}"
+        puts "Number of schemas in list: #{schema_files.size}"
+        puts "Cache: #{cache_path}"
+        puts "--------------------------------"
+
+        # Process each file with caching
+        schema_files.each_with_index do |file, index|
+          puts "Processing file #{index + 1}/#{schema_files.size}: #{file}"
+
+          # Benchmark with caching
+          Expressir::Benchmark.measure_with_cache(file, cache_path) do |path|
+            Expressir::Express::Parser.from_file(path)
+          end
+
+          puts "--------------------------------"
+        end
+      end
+
+      def generate_temp_cache_path
+        require "tempfile"
+        Tempfile.new(["expressir_cache", ".bin"]).path
+      end
     end
 
     desc "validate *PATH", "validate EXPRESS schema located at PATH"

data/lib/expressir/config.rb

@@ -12,10 +12,49 @@ module Expressir
   end
 
   class Configuration
-    attr_accessor :logs
+    attr_accessor :logs, :benchmark_enabled, :benchmark_ips, :benchmark_verbose,
+                  :benchmark_save, :benchmark_iterations, :benchmark_warmup, :benchmark_parallel,
+                  :benchmark_format
 
     def initialize
       @logs = %i(error)
+      # Enable benchmarking via environment variable
+      @benchmark_enabled = ENV["EXPRESSIR_BENCHMARK"] == "true"
+      # Use benchmark-ips for detailed statistics
+      @benchmark_ips = ENV["EXPRESSIR_BENCHMARK_IPS"] == "true"
+      # Show verbose output for benchmarking
+      @benchmark_verbose = ENV["EXPRESSIR_BENCHMARK_VERBOSE"] == "true"
+      # Save benchmark results to file
+      @benchmark_save = ENV["EXPRESSIR_BENCHMARK_SAVE"] == "true"
+      # Number of iterations for benchmark-ips
+      @benchmark_iterations = (ENV["EXPRESSIR_BENCHMARK_ITERATIONS"] || "3").to_i
+      # Warmup time for benchmark-ips in seconds
+      @benchmark_warmup = (ENV["EXPRESSIR_BENCHMARK_WARMUP"] || "1").to_i
+      # Enable parallel processing (for future implementation)
+      @benchmark_parallel = ENV["EXPRESSIR_BENCHMARK_PARALLEL"] == "true"
+      # Output format for benchmark results (default, json, csv)
+      @benchmark_format = ENV["EXPRESSIR_BENCHMARK_FORMAT"] || "default"
+    end
+
+    # Helper methods for checking benchmark settings
+    def benchmark_enabled?
+      @benchmark_enabled
+    end
+
+    def benchmark_ips?
+      @benchmark_enabled && @benchmark_ips
+    end
+
+    def benchmark_verbose?
+      @benchmark_enabled && @benchmark_verbose
+    end
+
+    def benchmark_save?
+      @benchmark_enabled && @benchmark_save
+    end
+
+    def benchmark_parallel?
+      @benchmark_enabled && @benchmark_parallel
     end
   end
 

data/lib/expressir/express/cache.rb

@@ -38,7 +38,7 @@ module Expressir
         cache = Model::Cache.from_yaml(yaml)
 
         if cache.version != version
-          raise Error.new("Cache version mismatch, cache version is #{cache.version}, Expressir version is #{version}")
+          raise Error::CacheVersionMismatchError.new(cache.version, version)
         end
 
         cache

data/lib/expressir/express/error.rb

@@ -0,0 +1,87 @@
+module Expressir
+  module Express
+    # Module containing all Express-related errors
+    module Error
+      # Base error class for Express errors
+      class ExpressError < StandardError; end
+
+      # Error raised when a schema file fails to parse
+      class SchemaParseFailure < ExpressError
+        attr_reader :filename, :original_error, :parse_failure_cause
+
+        # Initialize a new SchemaParseFailure error
+        # @param filename [String] The name of the file that failed to parse
+        # @param original_error [Parslet::ParseFailed] The original parsing error
+        def initialize(filename, original_error)
+          @filename = filename
+          @original_error = original_error
+          @parse_failure_cause = original_error.parse_failure_cause
+          super("Failed to parse schema in file '#{filename}': #{original_error.message}")
+        end
+      end
+
+      # Error raised when there's a version mismatch in the cache
+      class CacheVersionMismatchError < ExpressError
+        attr_reader :cache_version, :expressir_version
+
+        # Initialize a new CacheVersionMismatchError
+        # @param cache_version [String] The version of the cache file
+        # @param expressir_version [String] The current Expressir version
+        def initialize(cache_version, expressir_version)
+          @cache_version = cache_version
+          @expressir_version = expressir_version
+          super("Cache version mismatch, cache version is #{cache_version}, Expressir version is #{expressir_version}")
+        end
+      end
+
+      # Base class for visitor-related errors
+      class VisitorError < ExpressError; end
+
+      # Error raised when visitor encounters invalid state
+      class VisitorInvalidStateError < VisitorError
+        # Initialize a new VisitorInvalidStateError
+        # @param message [String] Additional error information
+        def initialize(message = "Invalid state")
+          super("Visitor error: #{message}")
+        end
+      end
+
+      # Error raised when visitor encounters invalid input
+      class VisitorInvalidInputError < VisitorError
+        # Initialize a new VisitorInvalidInputError
+        # @param message [String] Additional error information
+        def initialize(message)
+          super("Invalid input error: #{message}")
+        end
+      end
+
+      # Error raised when a required method is missing
+      class FormatterMethodMissingError < ExpressError
+        # Initialize a new FormatterMethodMissingError
+        # @param formatter [String] Name of the formatter
+        # @param method [String] Name of the missing method
+        def initialize(formatter, method = nil)
+          method_msg = method ? " Missing method: #{method}" : " Missing required method."
+          super("Formatter error in #{formatter}.#{method_msg}")
+        end
+      end
+
+      # Error raised when reference resolution fails
+      class VisitorReferenceResolutionError < VisitorError
+        attr_reader :source, :reference
+
+        # Initialize a new VisitorReferenceResolutionError
+        # @param source [String] Source of the reference
+        # @param reference [String] The reference that failed to resolve
+        def initialize(source, reference)
+          @source = source
+          @reference = reference
+          super("Failed to resolve reference '#{reference}' from '#{source}'")
+        end
+      end
+    end
+
+    # For backward compatibility
+    CacheVersionMismatchError = Error::CacheVersionMismatchError
+  end
+end

data/lib/expressir/express/hyperlink_formatter.rb

@@ -9,7 +9,7 @@ module Expressir
       # @!visibility private
       def self.included(mod)
         if !mod.superclass.private_method_defined? :format_references_simple_reference
-          raise "Missing method"
+          raise Error::FormatterMethodMissingError.new("HyperlinkFormatter", "format_references_simple_reference")
         end
       end