expressir 2.3.7 → 2.4.1

data/lib/expressir/model/model_element.rb

@@ -4,6 +4,63 @@ module Expressir
   module Model
     # Base model element
     class ModelElement < Lutaml::Model::Serializable
+      # ---- Collection-attributes macro (TODO.bugs/12) ----
+      #
+      # Each model class declares which attributes hold child collections
+      # via `collection_attributes :foo, :bar, ...`. The declarations
+      # auto-register into the global registry, eliminating the need for
+      # a hand-maintained hash in NodePositionIndex.
+
+      # Returns the global registry: class → array of attr symbols.
+      def self.collection_registry
+        @collection_registry ||= {}
+      end
+
+      # Returns the collection attributes declared on this class (empty
+      # if none declared).
+      def self.collection_attributes_list
+        @collection_attributes || []
+      end
+
+      # Declare which attributes on this model class hold child collections
+      # that should be traversed by tree-walkers (NodePositionIndex,
+      # RemarkAttacher, ScopeResolver). Also registers this class in the
+      # global collection registry so NodePositionIndex can derive its
+      # COLLECTION_REGISTRY from the model instead of duplicating it.
+      def self.collection_attributes(*attrs)
+        @collection_attributes = attrs.freeze
+        ModelElement.collection_registry[self] = attrs
+      end
+
+      # ---- End collection-attributes macro ----
+
+      # ---- Child-attributes macro (TODO.bugs/15) ----
+      #
+      # Similar to collection_attributes, but for single-value ModelElement
+      # children (non-collection attributes that hold a ModelElement, like
+      # BinaryExpression#operand1). Used by RemarkAttacher for query
+      # traversal so the EXPRESSION_CHILDREN hash lives on the model.
+
+      # Returns the global registry: class → array of attr symbols.
+      def self.child_attributes_registry
+        @child_attributes_registry ||= {}
+      end
+
+      # Returns the child attributes declared on this class (empty if none).
+      def self.child_attributes_list
+        @child_attributes || []
+      end
+
+      # Declare which attributes on this model class hold single-value
+      # ModelElement children that should be traversed by the remark
+      # attacher's query-search.
+      def self.child_attributes(*attrs)
+        @child_attributes = attrs.freeze
+        ModelElement.child_attributes_registry[self] = attrs
+      end
+
+      # ---- End child-attributes macro ----
+
       SKIP_ATTRIBUTES = %i[parent _class].freeze
       # :parent is a special attribute that is used to store the parent of the current element
       # It is not a real attribute
@@ -98,10 +155,7 @@ module Expressir
       end
 
       def source
-        formatter = Class.new(Expressir::Express::Formatter) do
-          include Expressir::Express::HyperlinkFormatter
-        end
-        formatter.format(self)
+        Expressir::Express::SourceFormatter.format(self)
       end
 
       # @param [Hash] options
@@ -149,16 +203,9 @@ module Expressir
         current_scope = self
         target_node = nil
         loop do
-          # find in current scope
-          current_node = current_scope
-          path_parts.each do |current_path|
-            current_node = current_node.children_by_id[current_path]
-            break unless current_node
-          end
-          target_node = current_node
+          target_node = resolve_path_in_scope(current_scope, path_parts)
           break if target_node
 
-          # retry search in parent scope
           current_scope = current_scope.parent
           break unless current_scope
         end
@@ -170,6 +217,62 @@ module Expressir
         target_node
       end
 
+      # Walk `path_parts` through `scope`, resolving one part at a time.
+      # Handles `SELF\<supertype>.<attr>` qualifiers inline: when a part
+      # starts with `self\`, the next part is matched against the scope's
+      # redeclared attributes and disambiguated by the supertype name
+      # (issues #130 and #267).
+      def resolve_path_in_scope(scope, path_parts)
+        current_node = scope
+        pending_supertype = nil
+
+        path_parts.each do |current_path|
+          if current_path.start_with?("self\\")
+            pending_supertype = current_path.split("\\", 2).last
+            next
+          end
+
+          if pending_supertype
+            child = find_redeclared_by_supertype(current_node, current_path,
+                                                 pending_supertype)
+            return nil unless child
+
+            current_node = child
+            pending_supertype = nil
+          else
+            current_node = current_node.children_by_id[current_path]
+            return nil unless current_node
+          end
+        end
+
+        # If the path ended on a SELF qualifier (no attr name followed),
+        # resolution is incomplete.
+        pending_supertype ? nil : current_node
+      end
+
+      # Find a redeclared attribute among `scope`'s children whose id matches
+      # `attr_name` and whose supertype_attribute references the given
+      # `supertype` name. Returns nil if `scope` is not an Attribute container
+      # or no such child exists.
+      def find_redeclared_by_supertype(scope, attr_name, supertype)
+        attrs = scope.respond_to?(:attributes) ? scope.attributes : nil
+        return nil unless attrs
+
+        attrs.find do |child|
+          next false unless child.is_a?(Model::Declarations::Attribute)
+          next false unless child.id&.safe_downcase == attr_name
+
+          supertype_attr = child.supertype_attribute
+          next false unless supertype_attr.respond_to?(:ref)
+
+          group_ref = supertype_attr.ref
+          next false unless group_ref.respond_to?(:entity)
+
+          entity_ref = group_ref.entity
+          entity_ref&.id&.safe_downcase == supertype
+        end
+      end
+
       # @return [Array<Declaration>]
       def children
         []
@@ -188,12 +291,23 @@ module Expressir
         nil
       end
 
-      def to_s(no_remarks: false, formatter: nil)
+      # Format this element back into EXPRESS source text.
+      # @param no_remarks [Boolean] omit remarks from the output
+      # @param formatter [Express::Formatter, nil] use a specific formatter
+      # @return [String]
+      def format(no_remarks: false, formatter: nil)
         f = formatter || Express::Formatter.new(no_remarks: no_remarks)
-        f.no_remarks = no_remarks
         f.format(self)
       end
 
+      # No-arg delegator so string interpolation ("#{element}") still
+      # produces EXPRESS source rather than the default Object#to_s.
+      # Remark-free output is requested explicitly through
+      # #format(no_remarks: true); it is not this method's default.
+      def to_s
+        format
+      end
+
       # Add a remark to this element
       # @param remark_info [RemarkInfo] Remark to add
       def add_remark(remark_info)

data/lib/expressir/model/remark_format.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Model
+    # Single source of truth for the remark-format vocabulary.
+    #
+    # Reference: ISO 10303-11 §7.1.6 defines exactly two remark forms:
+    # the tail remark (`-- ... \n`) and the embedded remark (`(* ... *)`).
+    # Both the model (RemarkInfo) and the express-side scanner/attacher
+    # reference these constants instead of bare string literals, so a
+    # rename or extension lands in one place.
+    module RemarkFormat
+      TAIL = "tail"
+      EMBEDDED = "embedded"
+    end
+  end
+end

data/lib/expressir/model/remark_info.rb

@@ -5,19 +5,24 @@ module Expressir
     # Can include optional tags for associating remarks with specific items
     class RemarkInfo < Lutaml::Model::Serializable
       attribute :text, :string
-      attribute :format, :string, default: "embedded" # 'tail' or 'embedded'
+      attribute :format, :string, default: RemarkFormat::EMBEDDED
       attribute :tag, :string # optional remark tag like "entity.attr"
+      # See RemarkPlacement. nil = legacy placement.
+      attribute :placement, :string
+      # For TRAILING remarks, which body of the owner they close.
+      attribute :region, :string
+      attribute :source_offset, :integer # byte offset in source text
 
       # Check if this is a tail remark
       # @return [Boolean] True if format is 'tail'
       def tail?
-        format == "tail"
+        format == RemarkFormat::TAIL
       end
 
       # Check if this is an embedded remark
       # @return [Boolean] True if format is 'embedded'
       def embedded?
-        format == "embedded"
+        format == RemarkFormat::EMBEDDED
       end
 
       # Check if this remark has a tag
@@ -26,11 +31,32 @@ module Expressir
         !tag.nil? && !tag.empty?
       end
 
+      # Check if this remark should be emitted above its owning statement
+      # @return [Boolean] True if placement is 'leading'
+      def leading?
+        placement == RemarkPlacement::LEADING
+      end
+
+      # Check if this remark trails its owning statement on the same line
+      # @return [Boolean] True if placement is 'inline'
+      def inline?
+        placement == RemarkPlacement::INLINE
+      end
+
+      # Check if this remark closes the given body of its owning node
+      # @param name [Symbol, String] region attribute name
+      # @return [Boolean]
+      def trailing_region?(name)
+        placement == RemarkPlacement::TRAILING && region == name.to_s
+      end
+
       # YAML serialization
       yaml do
         map "text", to: :text
         map "format", to: :format
         map "tag", to: :tag
+        map "placement", to: :placement
+        map "region", to: :region
       end
 
       # XML serialization
@@ -39,6 +65,8 @@ module Expressir
         map_element "text", to: :text
         map_element "format", to: :format
         map_element "tag", to: :tag
+        map_element "placement", to: :placement
+        map_element "region", to: :region
       end
     end
   end

data/lib/expressir/model/remark_placement.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Model
+    # Single source of truth for where a remark sits relative to the model
+    # element that owns it.
+    #
+    # The parser discards comments, so attachment reconstructs their position
+    # from source lines. Placement records that reconstruction, letting the
+    # formatter put the remark back where it was written:
+    #
+    # - LEADING — on its own line(s) directly above the owning statement.
+    # - TRAILING — on its own line(s) at the end of a body, before the closing
+    #   keyword. The owner is the body's owner, and RemarkInfo#region names
+    #   which body: an IF owns two, and they close at different keywords.
+    # - INLINE — on the same line as the owning statement, after its text.
+    #   Only single-line statements take these: appending to a multi-line
+    #   statement would move the remark down to its closing keyword.
+    #
+    # `nil` means the remark was attached by a legacy path, or predates
+    # placement tracking. Those keep their historical emission and must not
+    # be rendered by placement-aware emitters.
+    module RemarkPlacement
+      LEADING = "leading"
+      TRAILING = "trailing"
+      INLINE = "inline"
+    end
+  end
+end

data/lib/expressir/model/statements/alias.rb

@@ -4,8 +4,10 @@ module Expressir
       # Specified in ISO 10303-11:2004
       # - section 13.2 Alias statement
       class Alias < ModelElement
+        include Statement
         include Identifier
 
+        collection_attributes :statements
         attribute :expression, ModelElement
         attribute :statements, ModelElement, collection: true
         attribute :_class, :string, default: -> { self.class.name }

data/lib/expressir/model/statements/assignment.rb

@@ -4,12 +4,16 @@ module Expressir
       # Specified in ISO 10303-11:2004
       # - section 13.3 Assignment
       class Assignment < ModelElement
+        include Statement
+
+        child_attributes :expression
         attribute :ref, ModelElement
         attribute :expression, ModelElement
         attribute :_class, :string, default: -> { self.class.name }
 
         key_value do
           map "_class", to: :_class, render_default: true
+          map "untagged_remarks", to: :untagged_remarks
           map "ref", to: :ref
           map "expression", to: :expression
         end

data/lib/expressir/model/statements/case.rb

@@ -4,13 +4,34 @@ module Expressir
       # Specified in ISO 10303-11:2004
       # - section 13.4 Case statement
       class Case < ModelElement
+        include Statement
+
+        # The executable bodies of a CASE, exposed as ordered statement
+        # lists. Tree-walkers traverse these rather than `actions`, because
+        # a CaseAction is a label wrapper the parser gives no usable source
+        # position — the statement inside it carries the position that
+        # matters for placing comments.
+        collection_attributes :action_statements, :otherwise_statements
+
+        child_attributes :expression
         attribute :expression, ModelElement
         attribute :actions, CaseAction, collection: true
         attribute :otherwise_statement, ModelElement
         attribute :_class, :string, default: -> { self.class.name }
 
+        # @return [Array<ModelElement>] each action's statement, in order
+        def action_statements
+          Array(actions).filter_map(&:statement)
+        end
+
+        # @return [Array<ModelElement>] the OTHERWISE body, if present
+        def otherwise_statements
+          [otherwise_statement].compact
+        end
+
         key_value do
           map "_class", to: :_class, render_default: true
+          map "untagged_remarks", to: :untagged_remarks
           map "expression", to: :expression
           map "actions", to: :actions
           map "otherwise_statement", to: :otherwise_statement

data/lib/expressir/model/statements/case_action.rb

@@ -4,6 +4,7 @@ module Expressir
       # Specified in ISO 10303-11:2004
       # - section 13.4 Case statement
       class CaseAction < ModelElement
+        child_attributes :expression
         attribute :labels, ModelElement, collection: true
         attribute :statement, ModelElement
         attribute :_class, :string, default: -> { self.class.name }

data/lib/expressir/model/statements/compound.rb

@@ -4,11 +4,15 @@ module Expressir
       # Specified in ISO 10303-11:2004
       # - section 13.5 Compound statement
       class Compound < ModelElement
+        include Statement
+
+        collection_attributes :statements
         attribute :statements, ModelElement, collection: true
         attribute :_class, :string, default: -> { self.class.name }
 
         key_value do
           map "_class", to: :_class, render_default: true
+          map "untagged_remarks", to: :untagged_remarks
           map "statements", to: :statements
         end
       end

data/lib/expressir/model/statements/escape.rb

@@ -4,10 +4,13 @@ module Expressir
       # Specified in ISO 10303-11:2004
       # - section 13.6 Escape statement
       class Escape < ModelElement
+        include Statement
+
         attribute :_class, :string, default: -> { self.class.name }
 
         key_value do
           map "_class", to: :_class, render_default: true
+          map "untagged_remarks", to: :untagged_remarks
         end
       end
     end

data/lib/expressir/model/statements/if.rb

@@ -4,6 +4,10 @@ module Expressir
       # Specified in ISO 10303-11:2004
       # - section 13.7 If ... Then ... Else statement
       class If < ModelElement
+        include Statement
+
+        collection_attributes :statements, :else_statements
+        child_attributes :expression
         attribute :expression, ModelElement
         attribute :statements, ModelElement, collection: true
         attribute :else_statements, ModelElement, collection: true
@@ -11,6 +15,7 @@ module Expressir
 
         key_value do
           map "_class", to: :_class, render_default: true
+          map "untagged_remarks", to: :untagged_remarks
           map "expression", to: :expression
           map "statements", to: :statements
           map "else_statements", to: :else_statements

data/lib/expressir/model/statements/null.rb

@@ -4,10 +4,13 @@ module Expressir
       # Specified in ISO 10303-11:2004
       # - section 13.1 Null (statement)
       class Null < ModelElement
+        include Statement
+
         attribute :_class, :string, default: -> { self.class.name }
 
         key_value do
           map "_class", to: :_class, render_default: true
+          map "untagged_remarks", to: :untagged_remarks
         end
       end
     end

data/lib/expressir/model/statements/procedure_call.rb

@@ -4,12 +4,15 @@ module Expressir
       # Specified in ISO 10303-11:2004
       # - section 13.8 Procedure call statement
       class ProcedureCall < ModelElement
+        include Statement
+
         attribute :procedure, ModelElement
         attribute :parameters, ModelElement, collection: true
         attribute :_class, :string, default: -> { self.class.name }
 
         key_value do
           map "_class", to: :_class, render_default: true
+          map "untagged_remarks", to: :untagged_remarks
           map "procedure", to: :procedure
           map "parameters", to: :parameters
         end

data/lib/expressir/model/statements/repeat.rb

@@ -4,8 +4,11 @@ module Expressir
       # Specified in ISO 10303-11:2004
       # - section 13.9 Repeat statement
       class Repeat < ModelElement
+        include Statement
         include Identifier
 
+        collection_attributes :statements
+        child_attributes :while_expression, :until_expression
         attribute :bound1, ModelElement
         attribute :bound2, ModelElement
         attribute :increment, ModelElement

data/lib/expressir/model/statements/return.rb

@@ -4,11 +4,14 @@ module Expressir
       # Specified in ISO 10303-11:2004
       # - section 13.10 Return statement
       class Return < ModelElement
+        include Statement
+
         attribute :expression, ModelElement
         attribute :_class, :string, default: -> { self.class.name }
 
         key_value do
           map "_class", to: :_class, render_default: true
+          map "untagged_remarks", to: :untagged_remarks
           map "expression", to: :expression
         end
       end

data/lib/expressir/model/statements/skip.rb

@@ -4,10 +4,13 @@ module Expressir
       # Specified in ISO 10303-11:2004
       # - section 13.11 Skip statement
       class Skip < ModelElement
+        include Statement
+
         attribute :_class, :string, default: -> { self.class.name }
 
         key_value do
           map "_class", to: :_class, render_default: true
+          map "untagged_remarks", to: :untagged_remarks
         end
       end
     end

data/lib/expressir/model.rb

@@ -1,10 +1,17 @@
 # lib/expressir/model.rb
 
-# Load marker modules for type checking
-require_relative "model/concerns"
-
 module Expressir
   module Model
+    # Marker modules — autoload the same concerns.rb file from each name.
+    # The first reference triggers the load; the file defines all seven markers.
+    autoload :HasId, "#{__dir__}/model/concerns"
+    autoload :HasRemarkItems, "#{__dir__}/model/concerns"
+    autoload :HasRemarks, "#{__dir__}/model/concerns"
+    autoload :ScopeContainer, "#{__dir__}/model/concerns"
+    autoload :HasInformalPropositions, "#{__dir__}/model/concerns"
+    autoload :HasWhereRules, "#{__dir__}/model/concerns"
+    autoload :Statement, "#{__dir__}/model/concerns"
+
     autoload :ModelElement, "#{__dir__}/model/model_element"
     autoload :Cache, "#{__dir__}/model/cache"
     autoload :ExpFile, "#{__dir__}/model/exp_file"
@@ -12,6 +19,8 @@ module Expressir
     autoload :Repository, "#{__dir__}/model/repository"
     autoload :RepositoryValidator, "#{__dir__}/model/repository_validator"
     autoload :DependencyResolver, "#{__dir__}/model/dependency_resolver"
+    autoload :RemarkFormat, "#{__dir__}/model/remark_format"
+    autoload :RemarkPlacement, "#{__dir__}/model/remark_placement"
     autoload :RemarkInfo, "#{__dir__}/model/remark_info"
     autoload :InterfaceValidator, "#{__dir__}/model/interface_validator"
     autoload :SearchEngine, "#{__dir__}/model/search_engine"

data/lib/expressir/package/builder.rb

@@ -31,7 +31,7 @@ module Expressir
         end
 
         # Create ZIP package
-        Zip::File.open(output_path, Zip::File::CREATE) do |zip|
+        Zip::File.open(output_path, create: true) do |zip|
           add_metadata(zip, metadata)
           add_schemas(zip, repository, options)
           add_indexes(zip, repository)
@@ -68,7 +68,7 @@ module Expressir
           description: options[:description],
           created_at: Time.now.utc.iso8601,
           created_by: "expressir",
-          expressir_version: Expressir::VERSION,
+          expressir_version: Expressir::Version::VERSION,
           express_mode: options[:express_mode],
           resolution_mode: options[:resolution_mode],
           serialization_format: options[:serialization_format],

data/lib/expressir/version.rb

@@ -1,3 +1,8 @@
 module Expressir
-  VERSION = "2.3.7".freeze
+  # Gem version. Wrapped in a Version module so that lib/expressir.rb can
+  # autoload it (Ruby autoload only works for module/class constants, not
+  # for string constants like `Expressir::VERSION`).
+  module Version
+    VERSION = "2.4.1".freeze
+  end
 end

data/lib/expressir.rb

@@ -1,6 +1,3 @@
-require_relative "expressir/version"
-require_relative "expressir/errors"
-
 require "lutaml/model"
 require "liquid" # To enable Lutaml::Model::Liquefiable
 
@@ -29,6 +26,44 @@ module Expressir
   autoload :Config, "#{__dir__}/expressir/config"
   extend Config
 
+  autoload :Version, "#{__dir__}/expressir/version"
+
+  # Error classes — autoload the same errors.rb file from each name.
+  # The first reference triggers the load; the file defines all 21 classes.
+  autoload :Error, "#{__dir__}/expressir/errors"
+  autoload :FileNotFoundError, "#{__dir__}/expressir/errors"
+  autoload :ManifestNotFoundError, "#{__dir__}/expressir/errors"
+  autoload :PackageNotFoundError, "#{__dir__}/expressir/errors"
+  autoload :SchemaNotFoundError, "#{__dir__}/expressir/errors"
+  autoload :UsageError, "#{__dir__}/expressir/errors"
+  autoload :MissingRequiredArgumentError, "#{__dir__}/expressir/errors"
+  autoload :InvalidOptionError, "#{__dir__}/expressir/errors"
+  autoload :ValidationError, "#{__dir__}/expressir/errors"
+  autoload :ManifestValidationError, "#{__dir__}/expressir/errors"
+  autoload :SchemaValidationError, "#{__dir__}/expressir/errors"
+  autoload :ReferentialIntegrityError, "#{__dir__}/expressir/errors"
+  autoload :NoValidSchemaPathsError, "#{__dir__}/expressir/errors"
+  autoload :CommandError, "#{__dir__}/expressir/errors"
+  autoload :PackageBuildError, "#{__dir__}/expressir/errors"
+  autoload :PackageReadError, "#{__dir__}/expressir/errors"
+  autoload :PackageExtractError, "#{__dir__}/expressir/errors"
+  autoload :PackageValidationError, "#{__dir__}/expressir/errors"
+  autoload :PackageListError, "#{__dir__}/expressir/errors"
+  autoload :PackageSearchError, "#{__dir__}/expressir/errors"
+  autoload :PackageTreeError, "#{__dir__}/expressir/errors"
+
+  # Backward-compatible top-level VERSION constant.
+  # Expressir::VERSION is a string, which Ruby autoload cannot lazy-load
+  # (autoload only works for module/class constants). The actual value
+  # lives in Expressir::Version::VERSION, autoloaded on first reference.
+  # This const_missing triggers the autoload when Expressir::VERSION is
+  # referenced, then caches the result.
+  def self.const_missing(name)
+    return Version::VERSION if name == :VERSION
+
+    super
+  end
+
   autoload :Benchmark, "#{__dir__}/expressir/benchmark"
   autoload :Coverage, "#{__dir__}/expressir/coverage"