expressir 2.4.29-arm-linux-musl

data/lib/expressir/model/model_element.rb

@@ -0,0 +1,377 @@
+require "pathname"
+
+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 ----
+
+      # :source is skipped deliberately: its reader formats the node,
+      # and reading it during construction (attach_parent_to_children on
+      # a from_hash-built object whose attributes are not yet applied)
+      # would memoize an incomplete rendering forever.
+      SKIP_ATTRIBUTES = %i[parent _class source].freeze
+      # :parent is a special attribute that is used to store the parent of the current element
+      # It is not a real attribute
+      # attribute :parent, ModelElement
+      attr_accessor :parent
+
+      attribute :_class, :string, default: -> { self.class.name },
+                                  polymorphic_class: true
+      attribute :source, :string
+      attribute :source_offset, :integer
+      attribute :untagged_remarks, RemarkInfo, collection: true
+
+      POLYMORPHIC_CLASS_MAP = {
+        "Expressir::Model::Cache" => "Expressir::Model::Cache",
+        "Expressir::Model::ExpFile" => "Expressir::Model::ExpFile",
+        "Expressir::Model::Repository" => "Expressir::Model::Repository",
+        "Expressir::Model::RemarkInfo" => "Expressir::Model::RemarkInfo",
+        "Expressir::Model::DataTypes::Aggregate" => "Expressir::Model::DataTypes::Aggregate",
+        "Expressir::Model::DataTypes::Array" => "Expressir::Model::DataTypes::Array",
+        "Expressir::Model::DataTypes::Bag" => "Expressir::Model::DataTypes::Bag",
+        "Expressir::Model::DataTypes::Binary" => "Expressir::Model::DataTypes::Binary",
+        "Expressir::Model::DataTypes::Boolean" => "Expressir::Model::DataTypes::Boolean",
+        "Expressir::Model::DataTypes::EnumerationItem" => "Expressir::Model::DataTypes::EnumerationItem",
+        "Expressir::Model::DataTypes::Enumeration" => "Expressir::Model::DataTypes::Enumeration",
+        "Expressir::Model::DataTypes::GenericEntity" => "Expressir::Model::DataTypes::GenericEntity",
+        "Expressir::Model::DataTypes::Generic" => "Expressir::Model::DataTypes::Generic",
+        "Expressir::Model::DataTypes::Integer" => "Expressir::Model::DataTypes::Integer",
+        "Expressir::Model::DataTypes::List" => "Expressir::Model::DataTypes::List",
+        "Expressir::Model::DataTypes::Logical" => "Expressir::Model::DataTypes::Logical",
+        "Expressir::Model::DataTypes::Number" => "Expressir::Model::DataTypes::Number",
+        "Expressir::Model::DataTypes::Real" => "Expressir::Model::DataTypes::Real",
+        "Expressir::Model::DataTypes::Select" => "Expressir::Model::DataTypes::Select",
+        "Expressir::Model::DataTypes::Set" => "Expressir::Model::DataTypes::Set",
+        "Expressir::Model::DataTypes::String" => "Expressir::Model::DataTypes::String",
+        "Expressir::Model::Declarations::DerivedAttribute" => "Expressir::Model::Declarations::DerivedAttribute",
+        "Expressir::Model::Declarations::Attribute" => "Expressir::Model::Declarations::Attribute",
+        "Expressir::Model::Declarations::Constant" => "Expressir::Model::Declarations::Constant",
+        "Expressir::Model::Declarations::Entity" => "Expressir::Model::Declarations::Entity",
+        "Expressir::Model::Declarations::Function" => "Expressir::Model::Declarations::Function",
+        "Expressir::Model::Declarations::InterfaceItem" => "Expressir::Model::Declarations::InterfaceItem",
+        "Expressir::Model::Declarations::InverseAttribute" => "Expressir::Model::Declarations::InverseAttribute",
+        "Expressir::Model::Declarations::Interface" => "Expressir::Model::Declarations::Interface",
+        "Expressir::Model::Declarations::InterfacedItem" => "Expressir::Model::Declarations::InterfacedItem",
+        "Expressir::Model::Declarations::Parameter" => "Expressir::Model::Declarations::Parameter",
+        "Expressir::Model::Declarations::Procedure" => "Expressir::Model::Declarations::Procedure",
+        "Expressir::Model::Declarations::RemarkItem" => "Expressir::Model::Declarations::RemarkItem",
+        "Expressir::Model::Declarations::InformalPropositionRule" => "Expressir::Model::Declarations::InformalPropositionRule",
+        "Expressir::Model::Declarations::Rule" => "Expressir::Model::Declarations::Rule",
+        "Expressir::Model::Declarations::SchemaVersionItem" => "Expressir::Model::Declarations::SchemaVersionItem",
+        "Expressir::Model::Declarations::SchemaVersion" => "Expressir::Model::Declarations::SchemaVersion",
+        "Expressir::Model::Declarations::Schema" => "Expressir::Model::Declarations::Schema",
+        "Expressir::Model::Declarations::SubtypeConstraint" => "Expressir::Model::Declarations::SubtypeConstraint",
+        "Expressir::Model::Declarations::Type" => "Expressir::Model::Declarations::Type",
+        "Expressir::Model::Declarations::UniqueRule" => "Expressir::Model::Declarations::UniqueRule",
+        "Expressir::Model::Declarations::Variable" => "Expressir::Model::Declarations::Variable",
+        "Expressir::Model::Declarations::WhereRule" => "Expressir::Model::Declarations::WhereRule",
+        "Expressir::Model::Expressions::AggregateInitializerItem" => "Expressir::Model::Expressions::AggregateInitializerItem",
+        "Expressir::Model::Expressions::AggregateInitializer" => "Expressir::Model::Expressions::AggregateInitializer",
+        "Expressir::Model::Expressions::BinaryExpression" => "Expressir::Model::Expressions::BinaryExpression",
+        "Expressir::Model::Expressions::EntityConstructor" => "Expressir::Model::Expressions::EntityConstructor",
+        "Expressir::Model::Expressions::FunctionCall" => "Expressir::Model::Expressions::FunctionCall",
+        "Expressir::Model::Expressions::Interval" => "Expressir::Model::Expressions::Interval",
+        "Expressir::Model::Expressions::QueryExpression" => "Expressir::Model::Expressions::QueryExpression",
+        "Expressir::Model::Expressions::UnaryExpression" => "Expressir::Model::Expressions::UnaryExpression",
+        "Expressir::Model::Literals::Binary" => "Expressir::Model::Literals::Binary",
+        "Expressir::Model::Literals::Integer" => "Expressir::Model::Literals::Integer",
+        "Expressir::Model::Literals::Logical" => "Expressir::Model::Literals::Logical",
+        "Expressir::Model::Literals::Real" => "Expressir::Model::Literals::Real",
+        "Expressir::Model::Literals::String" => "Expressir::Model::Literals::String",
+        "Expressir::Model::References::AttributeReference" => "Expressir::Model::References::AttributeReference",
+        "Expressir::Model::References::GroupReference" => "Expressir::Model::References::GroupReference",
+        "Expressir::Model::References::IndexReference" => "Expressir::Model::References::IndexReference",
+        "Expressir::Model::References::SimpleReference" => "Expressir::Model::References::SimpleReference",
+        "Expressir::Model::Statements::Alias" => "Expressir::Model::Statements::Alias",
+        "Expressir::Model::Statements::Assignment" => "Expressir::Model::Statements::Assignment",
+        "Expressir::Model::Statements::CaseAction" => "Expressir::Model::Statements::CaseAction",
+        "Expressir::Model::Statements::Case" => "Expressir::Model::Statements::Case",
+        "Expressir::Model::Statements::Compound" => "Expressir::Model::Statements::Compound",
+        "Expressir::Model::Statements::Escape" => "Expressir::Model::Statements::Escape",
+        "Expressir::Model::Statements::If" => "Expressir::Model::Statements::If",
+        "Expressir::Model::Statements::Null" => "Expressir::Model::Statements::Null",
+        "Expressir::Model::Statements::ProcedureCall" => "Expressir::Model::Statements::ProcedureCall",
+        "Expressir::Model::Statements::Repeat" => "Expressir::Model::Statements::Repeat",
+        "Expressir::Model::Statements::Return" => "Expressir::Model::Statements::Return",
+        "Expressir::Model::Statements::Skip" => "Expressir::Model::Statements::Skip",
+        "Expressir::Model::SupertypeExpressions::BinarySupertypeExpression" => "Expressir::Model::SupertypeExpressions::BinarySupertypeExpression",
+        "Expressir::Model::SupertypeExpressions::OneofSupertypeExpression" => "Expressir::Model::SupertypeExpressions::OneofSupertypeExpression",
+      }.freeze
+
+      key_value do
+        map "_class", to: :_class, render_default: true,
+                      polymorphic_map: POLYMORPHIC_CLASS_MAP
+        # Hydrate-only: byte positions ride the wire (Rust core path)
+        # without ever appearing in to_hash — the serialized shape stays
+        # identical to the Ruby-built model.
+        map "source_offset", to: :source_offset, serialize: false
+      end
+
+      def source
+        # Formatting is not free and callers probe `source` repeatedly while
+        # walking the tree (position index, remark attachment), so the text is
+        # computed once per node. Deliberately NOT @source: that ivar holds
+        # the raw source span lutaml-model's `source=` stores when
+        # include_source is on, and readers must keep seeing formatted text.
+        @formatted_source ||= Expressir::Express::SourceFormatter.format(self) # rubocop:disable Naming/MemoizedInstanceVariableName
+      end
+
+      # @param [Hash] options
+      def initialize(_options = {})
+        super
+        attach_parent_to_children
+      end
+
+      # @return [String]
+      def path
+        # this creates an implicit scope
+        return if is_a?(Statements::Alias) || is_a?(Statements::Repeat) || is_a?(Expressions::QueryExpression)
+
+        current_node = self
+        path_parts = []
+        loop do
+          # Skip adding the id if this is a RemarkItem that belongs to an InformalPropositionRule
+          # and has the same id as its parent
+          if !(current_node.is_a? References::SimpleReference) && current_node.is_a?(HasId) &&
+              !(is_a?(Declarations::RemarkItem) &&
+                parent.is_a?(Declarations::InformalPropositionRule) &&
+                id == parent.id)
+            path_parts << current_node.id
+          end
+
+          current_node = current_node.parent
+          break unless current_node
+        end
+
+        return if path_parts.empty?
+
+        path_parts.reverse.join(".")
+      end
+
+      # @param [String] path
+      # @return [ModelElement]
+      def find(path)
+        return self if path.nil? || path.empty?
+
+        path_parts = path.safe_downcase.split(".").map do |current_path|
+          _, _, current_path = current_path.rpartition(":") # ignore prefix
+          current_path
+        end
+
+        current_scope = self
+        target_node = nil
+        loop do
+          target_node = resolve_path_in_scope(current_scope, path_parts)
+          break if target_node
+
+          current_scope = current_scope.parent
+          break unless current_scope
+        end
+
+        if target_node.is_a? Model::Declarations::InterfacedItem
+          target_node = target_node.base_item
+        end
+
+        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
+
+      # Wire the parent pointers of this node's entire subtree. Needed
+      # for models materialized outside the builders (e.g. hydrated
+      # from the Rust core path), whose parents start unset.
+      def wire_parents(parent = nil)
+        self.parent = parent
+        self.class.attributes.each_key do |attr|
+          next if SKIP_ATTRIBUTES.include?(attr) || attr == :parent
+
+          value = public_send(attr)
+          case value
+          when Array
+            value.each { |v| v.wire_parents(self) if v.is_a?(ModelElement) }
+          when ModelElement
+            value.wire_parents(self)
+          end
+        end
+      end
+
+      # @return [Array<Declaration>]
+      def children
+        []
+      end
+
+      # @return [Hash<String, Declaration>]
+      def children_by_id
+        @children_by_id ||= children.select(&:id).to_h do |x|
+          [x.id.safe_downcase, x]
+        end
+      end
+
+      # @return [nil]
+      def reset_children_by_id
+        @children_by_id = nil
+        nil
+      end
+
+      # 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.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)
+        self.untagged_remarks ||= []
+        return unless remark_info.is_a?(RemarkInfo)
+
+        untagged_remarks << remark_info
+      end
+
+      private
+
+      # @return [nil]
+      def attach_parent_to_children
+        self.class.attributes.each_pair do |symbol, _lutaml_attr|
+          next if SKIP_ATTRIBUTES.include?(symbol)
+
+          value = public_send(symbol)
+
+          case value
+          when Array
+            value.each do |val|
+              if val.is_a?(ModelElement)
+                val.parent = self
+              end
+            end
+          when ModelElement
+            value.parent = self
+          end
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/expressir/model/references/attribute_reference.rb

@@ -0,0 +1,19 @@
+module Expressir
+  module Model
+    module References
+      # Specified in ISO 10303-11:2004
+      # - section 12.7.3 Attribute references
+      class AttributeReference < ModelElement
+        attribute :ref, ModelElement
+        attribute :attribute, ModelElement
+        attribute :_class, :string, default: -> { self.class.name }
+
+        key_value do
+          map "_class", to: :_class, render_default: true
+          map "ref", to: :ref
+          map "attribute", to: :attribute
+        end
+      end
+    end
+  end
+end

data/lib/expressir/model/references/group_reference.rb

@@ -0,0 +1,19 @@
+module Expressir
+  module Model
+    module References
+      # Specified in ISO 10303-11:2004
+      # - section 12.7.4 Group references
+      class GroupReference < ModelElement
+        attribute :ref, ModelElement
+        attribute :entity, ModelElement
+        attribute :_class, :string, default: -> { self.class.name }
+
+        key_value do
+          map "_class", to: :_class, render_default: true
+          map "ref", to: :ref
+          map "entity", to: :entity
+        end
+      end
+    end
+  end
+end

data/lib/expressir/model/references/index_reference.rb

@@ -0,0 +1,23 @@
+module Expressir
+  module Model
+    module References
+      # Specified in ISO 10303-11:2004
+      # - section 12.3.1 Binary indexing
+      # - section 12.5.1 String indexing
+      # - section 12.6.1 Aggregate indexing
+      class IndexReference < ModelElement
+        attribute :ref, ModelElement
+        attribute :index1, ModelElement
+        attribute :index2, ModelElement
+        attribute :_class, :string, default: -> { self.class.name }
+
+        key_value do
+          map "_class", to: :_class, render_default: true
+          map "ref", to: :ref
+          map "index1", to: :index1
+          map "index2", to: :index2
+        end
+      end
+    end
+  end
+end

data/lib/expressir/model/references/simple_reference.rb

@@ -0,0 +1,21 @@
+module Expressir
+  module Model
+    module References
+      # Specified in ISO 10303-11:2004
+      # - section 12.7.1 Simple references
+      class SimpleReference < ModelElement
+        attribute :id, :string
+        attribute :ref, ModelElement
+        attribute :base_path, :string
+        attribute :_class, :string, default: -> { self.class.name }
+
+        key_value do
+          map "_class", to: :_class, render_default: true
+          map "id", to: :id
+          map "ref", to: :ref
+          map "base_path", to: :base_path
+        end
+      end
+    end
+  end
+end

data/lib/expressir/model/references.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Model
+    module References
+      autoload :AttributeReference, "#{__dir__}/references/attribute_reference"
+      autoload :GroupReference, "#{__dir__}/references/group_reference"
+      autoload :IndexReference, "#{__dir__}/references/index_reference"
+      autoload :SimpleReference, "#{__dir__}/references/simple_reference"
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+module Expressir
+  module Model
+    # Represents a remark with its format and optional tag
+    # Supports both tail remarks (-- ...) and embedded remarks ((* ... *))
+    # Can include optional tags for associating remarks with specific items
+    class RemarkInfo < Lutaml::Model::Serializable
+      attribute :text, :string
+      attribute :format, :string, default: RemarkFormat::EMBEDDED
+      attribute :tag, :string # optional remark tag like "entity.attr"
+      # See RemarkPlacement. nil = legacy placement.
+      attribute :placement, :string
+      # Qualifies the placement. For TRAILING, which body of the owner the
+      # remark closes, named by that body's attribute. For INLINE,
+      # RemarkPlacement::OPENER_REGION when it trailed a compound statement's
+      # opening line rather than a whole statement.
+      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 == RemarkFormat::TAIL
+      end
+
+      # Check if this is an embedded remark
+      # @return [Boolean] True if format is 'embedded'
+      def embedded?
+        format == RemarkFormat::EMBEDDED
+      end
+
+      # Check if this remark has a tag
+      # @return [Boolean] True if tag is present
+      def tagged?
+        !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 trailed the opening line of a statement spanning
+      # several lines, as in `IF x THEN -- why`
+      # @return [Boolean]
+      def opener?
+        inline? && region == RemarkPlacement::OPENER_REGION
+      end
+
+      # Check if this INLINE remark belongs after a mid-construct keyword of
+      # its owning construct — `ELSE -- why`, `OTHERWISE : -- why` — rather
+      # than after the statement's closing keyword.
+      # @param name [Symbol, String] a RemarkPlacement region constant
+      # @return [Boolean]
+      def inline_region?(name)
+        inline? && region == name.to_s
+      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
+      xml do
+        element "remark_info"
+        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
+end

data/lib/expressir/model/remark_placement.rb

@@ -0,0 +1,42 @@
+# 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.
+    #   Emitted after the whole statement, which for a single-line one is the
+    #   line it was written on. RemarkInfo#region separates the other case:
+    #   OPENER_REGION means the remark trailed the opening line of a statement
+    #   spanning several lines, as in `IF x THEN -- why`, and belongs back on
+    #   that opener rather than after the 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"
+
+      # Region of an INLINE remark that trailed a compound statement's opener.
+      OPENER_REGION = "opener"
+
+      # Regions of INLINE remarks that trailed a mid-construct keyword line —
+      # `ELSE -- why` or `OTHERWISE : -- why`. The owning construct is the
+      # enclosing IF / CASE, and the remark belongs back after that keyword,
+      # not after the construct's closing END_.
+      ELSE_REGION = "else"
+      OTHERWISE_REGION = "otherwise"
+    end
+  end
+end