expressir 1.2.11-aarch64-linux → 2.4.29-aarch64-linux

data/lib/expressir/errors.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Expressir
+  # Base error class with details support
+  class Error < StandardError
+    attr_reader :details
+
+    def initialize(message = nil, details: nil)
+      @details = details
+      super(message)
+    end
+  end
+
+  # File/Resource Errors
+  class FileNotFoundError < Error
+    attr_reader :file_path, :file_type
+
+    def initialize(file_path, file_type: nil)
+      @file_path = file_path
+      @file_type = file_type
+      super("#{file_type || 'File'} not found: #{file_path}")
+    end
+  end
+
+  class ManifestNotFoundError < FileNotFoundError
+    def initialize(file_path)
+      super(file_path, file_type: "Manifest file")
+    end
+  end
+
+  class PackageNotFoundError < FileNotFoundError
+    def initialize(file_path)
+      super(file_path, file_type: "Package file")
+    end
+  end
+
+  class SchemaNotFoundError < FileNotFoundError
+    def initialize(file_path)
+      super(file_path, file_type: "Schema file")
+    end
+  end
+
+  # Usage/Argument Errors
+  class UsageError < Error
+    attr_reader :usage_hint
+
+    def initialize(message, usage_hint: nil)
+      @usage_hint = usage_hint
+      super(message)
+    end
+  end
+
+  class MissingRequiredArgumentError < UsageError; end
+
+  class InvalidOptionError < UsageError
+    attr_reader :option_name, :valid_options
+
+    def initialize(option_name, value, valid_options: nil)
+      @option_name = option_name
+      @valid_options = valid_options
+      msg = "Invalid value '#{value}' for #{option_name}"
+      msg += ". Valid options: #{valid_options.join(', ')}" if valid_options
+      super(msg)
+    end
+  end
+
+  # Validation Errors
+  class ValidationError < Error
+    attr_reader :errors
+
+    def initialize(message, errors: [])
+      @errors = errors
+      super(message)
+    end
+  end
+
+  class ManifestValidationError < ValidationError; end
+  class SchemaValidationError < ValidationError; end
+
+  class ReferentialIntegrityError < ValidationError
+    attr_reader :unresolved_references
+
+    def initialize(unresolved_references,
+message: "Referential integrity check failed")
+      @unresolved_references = unresolved_references
+      super(message)
+    end
+  end
+
+  class NoValidSchemaPathsError < ValidationError
+    def initialize(message = "No valid schema paths found")
+      super
+    end
+  end
+
+  # Command Errors (for rescue blocks)
+  class CommandError < Error
+    attr_reader :command_name
+
+    def initialize(message, command_name: nil)
+      @command_name = command_name
+      super(message)
+    end
+  end
+
+  class PackageBuildError < CommandError; end
+  class PackageReadError < CommandError; end
+  class PackageExtractError < CommandError; end
+  class PackageValidationError < CommandError; end
+  class PackageListError < CommandError; end
+  class PackageSearchError < CommandError; end
+  class PackageTreeError < CommandError; end
+end

data/lib/expressir/express/adoc_hyperlink_formatter.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Express
+    # HyperlinkFormatter variant emitting AsciiDoc xref macros instead
+    # of the legacy stepmod +{{{<<express:...>>}}}+ markup: a reference
+    # to schema.item renders as +<<schema.item,item>>+, the anchor
+    # namespace schema document pages emit (expressir #255 / iso-10303
+    # #41). With +subs="+macros"+ source blocks the links go live.
+    module AdocHyperlinkFormatter
+      # @!visibility private
+      def self.included(mod)
+        unless mod.superclass <= Expressir::Express::Formatter
+          raise Error::FormatterMethodMissingError.new("AdocHyperlinkFormatter",
+                                                       "format_references_simple_reference")
+        end
+      end
+
+      def format_references_simple_reference(node)
+        return node.id unless node.base_path
+
+        parts = node.base_path.split(".")
+        return node.id if parts.size < 2
+
+        anchor = parts[-2, 2].join(".")
+        "<<#{anchor},#{node.id}>>"
+      end
+    end
+  end
+end

data/lib/expressir/express/adoc_source_formatter.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Express
+    # Pre-built Formatter subclass rendering the FULL schema with
+    # cross-references as AsciiDoc xref macros — the document-page
+    # counterpart of SourceFormatter (Schema#formatted_hyperlinked_adoc).
+    class AdocSourceFormatter < Formatter
+      include AdocHyperlinkFormatter
+    end
+  end
+end

data/lib/expressir/express/ast_key_converter.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Express
+    # Converts native-AST CamelCase keys to the snake_case keys the
+    # builders consume.
+    #
+    # build() descends into child nodes whose subtrees the parent already
+    # converted, so unchanged containers are marked with an invisible
+    # instance variable and skipped on re-visits — without it, every
+    # subtree is re-scanned once per ancestor level (~60 convert calls per
+    # model node on real schemas). The marker is invisible to equality,
+    # hashing, and inspection.
+    class AstKeyConverter
+      SNAKED_MARKER = :@_expressir_keys_snaked
+      UPPERCASE_PATTERN = /[A-Z]/
+
+      class << self
+        # Thread-local snake_case conversion cache. Thread-local avoids the
+        # mutable-constant anti-pattern while remaining thread-safe. The
+        # cache is bounded by the number of unique AST node-type names.
+        def snake_case(name)
+          cache[name] ||= begin
+            str = name.to_s
+            if /^[a-z_]+$/.match?(str)
+              str.to_sym
+            else
+              str
+                .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                .downcase
+                .to_sym
+            end
+          end
+        end
+
+        # Returns the original object when no conversion is needed; the
+        # common no-conversion case allocates nothing and the conversion
+        # case walks the keys once.
+        def convert(obj)
+          case obj
+          when Hash
+            return obj if obj.empty?
+            return obj if obj.instance_variable_defined?(SNAKED_MARKER)
+
+            keys = obj.keys
+            converted_values = nil
+            new_keys = nil
+
+            keys.each_with_index do |k, i|
+              val = obj[k]
+              case val
+              when Hash, Array
+                unless val.empty?
+                  converted_val = convert(val)
+                  (converted_values ||= {})[k] = converted_val unless converted_val.equal?(val)
+                end
+              end
+
+              if k.match?(UPPERCASE_PATTERN)
+                (new_keys ||= keys.dup)[i] = snake_case(k)
+              end
+            end
+
+            return mark_snaked(obj) unless new_keys || converted_values
+
+            result = {}
+            keys.each_with_index do |k, i|
+              key = new_keys&.[](i) || k
+              result[key] = converted_values&.key?(k) ? converted_values[k] : obj[k]
+            end
+            mark_snaked(result)
+          when Array
+            return obj if obj.empty?
+            return obj if obj.instance_variable_defined?(SNAKED_MARKER)
+
+            needs_conversion = false
+            result = []
+
+            obj.each do |item|
+              case item
+              when Hash, Array
+                next if item.empty?
+
+                converted = convert(item)
+                result << converted
+                needs_conversion = true unless converted.equal?(item)
+              else
+                result << item
+              end
+            end
+
+            needs_conversion ? mark_snaked(result) : mark_snaked(obj)
+          else
+            obj
+          end
+        end
+
+        private
+
+        def cache
+          Thread.current[:expressir_snake_case_cache] ||= {}
+        end
+
+        def mark_snaked(obj)
+          obj.instance_variable_set(SNAKED_MARKER, true)
+          obj
+        rescue FrozenError
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/expressir/express/builder.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Express
+    # Builder registry for AST node type handlers.
+    # Each builder is a callable object that transforms AST data into Model objects.
+    # This is the ONLY way to build models from AST - no Transformer fallback.
+    module Builder
+      class << self
+        # Thread-local key under which the current BuilderContext is stored
+        # for the duration of a build_with_remarks call. Recursive build
+        # calls read source/include_source from here instead of from
+        # class-level mutable state.
+        CONTEXT_KEY = :expressir_builder_context
+
+        # Returns the BuilderContext for the current thread, or nil if no
+        # build is in progress.
+        def current_context
+          Thread.current[CONTEXT_KEY]
+        end
+
+        # Convenience accessors — read from the current context.
+        def source
+          current_context&.source
+        end
+
+        def include_source
+          current_context&.include_source
+        end
+
+        # Register a builder for a node type.
+        # @param node_type [Symbol] The AST node type
+        # @param builder [#call] Optional callable that takes (ast_data)
+        # @yield Block that takes (ast_data) if builder not provided
+        def register(node_type, builder = nil, &block)
+          @register ||= {}
+          @register[node_type] = builder || block
+        end
+
+        # Build a Model object from AST data.
+        # @param ast [Hash] The AST with node type as key
+        # @return [Model::ModelElement] The built model object
+        def build(ast)
+          return nil unless ast
+
+          # Optimized: Hash is 90%+ of cases, check it first
+          case ast
+          when Hash
+            node_type = ast.keys.first
+            node_data = ast[node_type]
+
+            handler_key = AstKeyConverter.snake_case(node_type)
+            snake_data = AstKeyConverter.convert(node_data)
+
+            builder = @register[handler_key]
+            if builder
+              result = builder.call(snake_data)
+
+              # Fast path: single-key hash or non-nil result
+              if !result.nil? || ast.keys.length <= 1
+                attach_source_info(result, node_data)
+                return result
+              end
+
+              # Slow path: first-key builder returned nil in a multi-key
+              # hash. Try remaining keys for actual content. This handles
+              # grammar patterns like `element >> (op_comma >> element).repeat`
+              # which produce {:op_comma => ..., :element => {...}} where
+              # the first key is an operator separator.
+              # Previously gated by a hand-maintained OPERATOR_TOKENS set;
+              # now tries all remaining keys unconditionally (TODO.bugs/21).
+              ast.each_key do |key|
+                next if key == node_type
+
+                h_key = AstKeyConverter.snake_case(key)
+                h_builder = @register[h_key]
+                next unless h_builder
+
+                n_data = ast[key]
+                s_data = AstKeyConverter.convert(n_data)
+                result = h_builder.call(s_data)
+
+                unless result.nil?
+                  attach_source_info(result, n_data)
+                  return result
+                end
+              end
+            else
+              raise Error::UnknownNodeTypeError, node_type
+            end
+            nil
+          when Array
+            ast.map do |item|
+              build(item)
+            end
+          when Parsanol::Slice
+            ast.to_s
+          else
+            ast
+          end
+        end
+
+        # Build with remark attachment.
+        #
+        # Sets up a BuilderContext as a thread-local for the duration of the
+        # build so recursive build calls can read source/include_source via
+        # `Builder.source` / `Builder.include_source`. The previous context
+        # (if any) is restored on exit so nested builds are reentrant.
+        def build_with_remarks(ast, source: nil, include_source: nil)
+          # Trigger BuilderRegistry autoload so all AST node type handlers
+          # are registered before build() runs. The reference to
+          # BuilderRegistry resolves the autoload defined in express.rb.
+          BuilderRegistry
+
+          previous = Thread.current[CONTEXT_KEY]
+          Thread.current[CONTEXT_KEY] = BuilderContext.new(
+            source: source,
+            include_source: include_source,
+          )
+
+          result = build(ast)
+
+          # Only attach remarks if include_source is explicitly true
+          # (nil means use default behavior - attach remarks)
+          if source && result && include_source != false
+            attacher = RemarkAttacher.new(source)
+            attacher.attach(result)
+          end
+
+          result
+        ensure
+          Thread.current[CONTEXT_KEY] = previous
+        end
+
+        # Check if a builder is registered for a node type.
+        def registered?(node_type)
+          @register&.key?(node_type)
+        end
+
+        # Get all registered node types.
+        def registered_types
+          @register&.keys || []
+        end
+
+        # Build optional (returns nil if ast is nil)
+        def build_optional(ast)
+          return nil unless ast
+
+          build(ast)
+        end
+
+        # Normalize a value to an Array for iteration.
+        # Handles: nil → [], Parsanol::Slice → [], Array → Array, other → [other]
+        def ensure_array(value)
+          return [] if value.nil?
+          return [] if value.is_a?(Parsanol::Slice)
+
+          value.is_a?(Array) ? value : [value]
+        end
+
+        # Build children (array of AST nodes)
+        # Optimized to avoid intermediate array allocations
+        def build_children(ast_array)
+          return [] if ast_array.nil?
+
+          # Handle Parsanol::Slice (empty Slices from optional rules)
+          # Convert to empty Array
+          if ast_array.is_a?(Parsanol::Slice)
+            return []
+          end
+
+          # Handle single element (common case)
+          unless ast_array.is_a?(Array)
+            return [build(ast_array)].compact
+          end
+
+          # Build result in single pass, avoiding flatten/compact/map chain
+          result = []
+          ast_array.each do |item|
+            next if item.nil?
+
+            # Empty Slices from optional rules should be treated as empty arrays
+            if item.is_a?(Parsanol::Slice)
+              next
+            end
+
+            case item
+            when Array
+              item.each do |sub|
+                result << build(sub) unless sub.nil?
+              end
+            else
+              built = build(item)
+              result << built if built
+            end
+          end
+          result
+        end
+
+        # Fast build methods - call registered builder directly without hash wrapping
+        # These are optimized for hot paths in expression building
+        # NOTE: These assume data is already snake_case (no key conversion needed)
+
+        # Call a registered builder directly with data (avoids hash wrapper allocation)
+        # @param node_type [Symbol] The node type key
+        # @param data The data to pass to the builder (already snake_case)
+        def build_node(node_type, data)
+          builder = @register&.[](node_type)
+          raise Error::UnknownNodeTypeError, node_type unless builder
+
+          builder.call(data)
+        end
+
+        # Keys containing uppercase need snake-casing; testing the key
+        # directly avoids allocating `to_s` strings per key per pass.
+        # Key conversion lives in AstKeyConverter (MECE: converting AST
+        # keys is not building models).
+        def extract_source_info(data)
+          return nil unless data
+
+          src = source
+          return nil unless src
+
+          slice = find_slice(data)
+          return nil unless slice
+
+          {
+            text: src[slice.offset...(slice.offset + slice.length)]&.strip,
+            offset: slice.offset,
+          }
+        end
+
+        def attach_source_info(result, data)
+          return unless source && result.is_a?(Expressir::Model::ModelElement)
+
+          source_info = extract_source_info(data)
+          return unless source_info
+
+          result.source_offset = source_info[:offset]
+          result.source = source_info[:text] if include_source
+        end
+
+        def find_slice(data, depth = 0)
+          return nil if depth > 10
+
+          case data
+          when Parsanol::Slice
+            data
+          when Hash
+            # Skip 'spaces' key which contains whitespace/comments before content
+            # Look for 'str' key first as it usually contains the actual content
+            if data.key?(:str) && data[:str].is_a?(Parsanol::Slice)
+              return data[:str]
+            end
+
+            # Then look in other keys, skipping 'spaces'
+            data.each do |key, value|
+              next if key == :spaces
+
+              return value if value.is_a?(Parsanol::Slice)
+
+              result = find_slice(value, depth + 1)
+              return result if result
+            end
+            nil
+          when Array
+            data.each do |item|
+              result = find_slice(item, depth + 1)
+              return result if result
+            end
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/expressir/express/builder_context.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Express
+    # Value object carrying the per-build context that Builder needs to
+    # attach source info to model elements.
+    #
+    # Stored as a thread-local by Builder.build_with_remarks so that recursive
+    # build calls can read `Builder.source` / `Builder.include_source` without
+    # the module mutating class-level state. Thread-local means concurrent
+    # builds in different threads don't corrupt each other; the save/restore
+    # pattern in build_with_remarks means nested builds are reentrant.
+    class BuilderContext
+      attr_reader :source, :include_source
+
+      def initialize(source:, include_source:)
+        @source = source
+        @include_source = include_source
+      end
+    end
+  end
+end