expressir 2.4.0 → 2.4.2

data/lib/expressir/express/remark_attacher.rb

@@ -4,6 +4,14 @@ module Expressir
   module Express
     # Handles attaching remarks (comments) to model elements after parsing.
     #
+    # Two collaborators sit behind the `attach` interface:
+    # - {ScopeResolver} answers "which scope contains line N?"
+    # - {NodePositionIndex} answers "which model node is nearest line N?"
+    #
+    # Remark scanning itself lives in {RemarkScanner}; line→byte lookup lives
+    # in {LineMap}. This class is the orchestrator: it walks the remarks, asks
+    # the collaborators for targets, and writes the remarks onto the model.
+    #
     # NOTE: Post-processing remark attachment has inherent limitations for scope-based
     # matching. Remarks with simple tags (like "WR1") inside scopes (TYPE, ENTITY, etc.)
     # cannot be perfectly matched without parsing context. This implementation prioritizes:
@@ -12,111 +20,84 @@ module Expressir
     # 3. NOT creating spurious schema-level items for ambiguous tags
     class RemarkAttacher
       # Type-driven registry: maps each model class to its collection attributes.
-      # Replaces runtime method probing (method_defined?) with explicit type declarations.
-      COLLECTION_REGISTRY = {
-        Model::Declarations::Schema => %i[
-          constants types entities subtype_constraints
-          functions rules procedures remark_items
-        ],
-        Model::Declarations::Entity => %i[
-          attributes derived_attributes inverse_attributes
-          unique_rules where_rules informal_propositions remark_items
-        ],
-        Model::Declarations::Function => %i[
-          parameters types entities subtype_constraints
-          functions procedures constants variables statements remark_items
-        ],
-        Model::Declarations::Procedure => %i[
-          parameters types entities subtype_constraints
-          functions procedures constants variables statements remark_items
-        ],
-        Model::Declarations::Rule => %i[
-          applies_to types entities subtype_constraints
-          functions procedures constants variables statements
-          where_rules informal_propositions remark_items
-        ],
-        Model::Declarations::Type => %i[
-          where_rules informal_propositions remark_items
-        ],
-        Model::ExpFile => %i[schemas],
-        Model::Statements::Compound => %i[statements],
-        Model::Statements::If => %i[statements],
-        Model::Statements::Alias => %i[statements],
-        Model::Statements::Repeat => %i[statements],
-      }.freeze
+      # Shared with {NodePositionIndex} via that class's own copy of the table.
+      # Two declarations rather than a cross-reference so each module is loadable
+      # on its own without forcing the other to load.
+      COLLECTION_REGISTRY = NodePositionIndex::COLLECTION_REGISTRY
+
+      # Collections holding executable statements — the regions a body
+      # comment can belong to.
+      STATEMENT_REGIONS = %i[
+        statements else_statements action_statements otherwise_statements
+      ].freeze
+
+      # Expression and statement child attributes are declared on the model
+      # via `child_attributes :foo, :bar, ...`. See TODO.bugs/15.
+      EXPRESSION_CHILDREN = Model::ModelElement.child_attributes_registry
+
+      # `WHERE <label> :` clause headers; the captured label maps to the
+      # 1-based line number(s) it appears on.
+      WHERE_CLAUSE_PATTERN = /\A\s*WHERE\s+(\w+)\s*:/i
 
       def initialize(source)
         @source = source
         @attached_spans = Set.new
         @line_map = LineMap.new(source.b)
         @model = nil
-        @source_lines = nil # cached @source.lines
-        @scope_map = nil # cached scope at each line number
+        @scope_resolver = nil
+        @node_index = nil
+        @owner_map = nil
+        @active_scope_map = nil
       end
 
       def attach(model)
         @model = model
         remarks = RemarkScanner.new(@source).scan
 
-        # Build nodes_with_positions ONCE for both tagged and untagged remark passes.
-        # This avoids double tree walk (381K nodes × 2 = 762K visits) which was
-        # the largest memory overhead in remark attachment (~430MB for large files).
-        nodes_with_positions = build_sorted_nodes_with_positions(model)
+        @node_index = NodePositionIndex.new(model, @line_map)
+        @scope_resolver = ScopeResolver.new(
+          source: @source,
+          model: model,
+          nodes_with_positions: @node_index.nodes,
+        )
 
-        attach_tagged_remarks(model, remarks, nodes_with_positions)
-        attach_untagged_remarks(remarks, nodes_with_positions)
+        attach_tagged_remarks(remarks)
+        attach_untagged_remarks(remarks)
 
-        # Free expensive data structures after attachment is complete.
-        # These are only needed during the attach process.
+        model
+      ensure
+        # Free expensive data structures once attachment is over. On the
+        # raising path this also drops the memoized ownership map, which
+        # would otherwise outlive the node index it was derived from.
         @source = nil
-        @source_lines = nil
-        @scope_map = nil
+        @scope_resolver = nil
+        @node_index = nil
         @line_map = nil
-
-        model
+        @owner_map = nil
+        @active_scope_map = nil
+        @source_lines_for_where_clause = nil
+        @where_clause_line_index = nil
       end
 
       private
 
-      # Remark extraction lives in {RemarkScanner}; this class only attaches.
-      # Line-number lookup is delegated to {LineMap} for O(log n) queries.
-
-      def source_lines
-        @source_lines ||= @source.lines
-      end
+      # ----- Tagged remark attachment -----
 
-      def get_line_number(position)
-        @line_map.line_number(position)
-      end
-
-      def attach_tagged_remarks(model, remarks, nodes_with_positions)
-        tagged = remarks.select { |r| r[:tag] }
+      def attach_tagged_remarks(remarks)
+        tagged = remarks.select(&:tag)
         return if tagged.empty?
 
-        @model = model
-
-        # Build scope map ONCE: O(file_lines) scan instead of O(n*file_lines) for n remarks
-        # This is the key optimization that makes scope lookup O(1) per remark
-        @scope_map ||= build_scope_map
-
-        tagged.sort_by(&:position).each do |remark|
+        tagged.each do |remark|
           next if @attached_spans.include?(remark.position)
 
           tag = remark.tag
           target = nil
 
-          # Find containing scope using pre-computed scope map (O(1))
-          # Falls back to position-based lookup if scope map doesn't have the line
-          containing_scope = find_containing_scope_by_name(remark.line)
-          containing_scope ||= find_containing_scope_position(remark.line,
-                                                              nodes_with_positions)
+          containing_scope = @scope_resolver.containing_scope_for(remark.line)
 
           # Check if this is an informal proposition tag (IP\d+)
           if tag.match?(/^IP\d+$/)
-            scope = containing_scope
-            if scope.nil?
-              scope = find_scope_by_source_text(remark.line)
-            end
+            scope = containing_scope || @scope_resolver.find_by_source_text(remark.line)
             if scope && supports_informal_propositions?(scope)
               target = create_or_find_informal_proposition(scope, tag)
             end
@@ -126,31 +107,28 @@ module Expressir
           if target.nil?
             # Handle prefixed tags like wr:WR1, ip:IP1, ur:UR1
             if tag.include?(":") && !tag.include?(".")
-              target = handle_prefixed_tag(tag, containing_scope, model,
-                                           get_schema_ids(model))
+              target = handle_prefixed_tag(tag, containing_scope, @model,
+                                           get_schema_ids(@model))
             end
 
             # Strategy 1: Try exact path lookup
             if target.nil?
-              target = find_by_exact_path(model, tag)
+              target = find_by_exact_path(@model, tag)
             end
 
             # Strategy 1b: For paths with dots, try with scope path prefix first
             if target.nil? && tag.include?(".")
-              # First, try building full path from containing scope
               if containing_scope && function_rule_procedure?(containing_scope)
                 scope_path = build_scope_path(containing_scope)
                 if scope_path
-                  full_path = "#{scope_path}.#{tag}"
-                  target = find_by_exact_path(model, full_path)
+                  target = find_by_exact_path(@model, "#{scope_path}.#{tag}")
                 end
               end
 
-              # Then try schema prefix
               if target.nil?
-                schema_ids = get_schema_ids(model)
+                schema_ids = get_schema_ids(@model)
                 schema_ids.each do |schema_id|
-                  target = find_by_exact_path(model, "#{schema_id}.#{tag}")
+                  target = find_by_exact_path(@model, "#{schema_id}.#{tag}")
                   break if target
                 end
               end
@@ -159,28 +137,24 @@ module Expressir
             # Strategy 2: For simple tags, find in containing scope first
             if target.nil? && !tag.include?(".")
               if containing_scope
-                # Search within the containing scope
                 target = find_node_in_scope(containing_scope, tag)
 
-                # Special handling for remarks inside WHERE clauses
                 if target.nil? && supports_where_rules?(containing_scope)
                   target = find_target_in_where_clause(containing_scope, tag,
                                                        remark.line)
                 end
 
-                # Only fall back to schema prefix if NOT inside a function/rule/procedure
                 if target.nil? && !function_rule_procedure?(containing_scope)
-                  schema_ids = get_schema_ids(model)
+                  schema_ids = get_schema_ids(@model)
                   schema_ids.each do |schema_id|
-                    target = find_by_exact_path(model, "#{schema_id}.#{tag}")
+                    target = find_by_exact_path(@model, "#{schema_id}.#{tag}")
                     break if target
                   end
                 end
               else
-                # No containing scope, try with schema prefix
-                schema_ids = get_schema_ids(model)
+                schema_ids = get_schema_ids(@model)
                 schema_ids.each do |schema_id|
-                  target = find_by_exact_path(model, "#{schema_id}.#{tag}")
+                  target = find_by_exact_path(@model, "#{schema_id}.#{tag}")
                   break if target
                 end
               end
@@ -188,146 +162,390 @@ module Expressir
 
             # Strategy 3: Create implicit item for qualified paths only
             if target.nil? && tag.include?(".")
-              # Try with scope path first
               if containing_scope && function_rule_procedure?(containing_scope)
                 scope_path = build_scope_path(containing_scope)
                 if scope_path
-                  full_path = "#{scope_path}.#{tag}"
-                  target = create_implicit_remark_item(model, full_path,
-                                                       get_schema_ids(model))
+                  target = create_implicit_remark_item(@model, "#{scope_path}.#{tag}",
+                                                       get_schema_ids(@model))
                 end
               end
-              # Fall back to schema prefix
               if target.nil?
-                target = create_implicit_remark_item(model, tag,
-                                                     get_schema_ids(model))
+                target = create_implicit_remark_item(@model, tag,
+                                                     get_schema_ids(@model))
               end
             end
 
             # Strategy 4: For simple tags at schema level, create implicit item
             if target.nil? && !tag.include?(".")
-              schema_ids = get_schema_ids(model)
+              schema_ids = get_schema_ids(@model)
               if schema_ids.any?
-                target = create_implicit_remark_item_at_schema(model, tag,
+                target = create_implicit_remark_item_at_schema(@model, tag,
                                                                schema_ids.first)
               end
             end
           end
 
           if target
-            add_remark(target, remark.text, format: remark.format, tag: remark.tag)
+            add_remark(target, remark.text, format: remark.format, tag: remark.tag,
+                                            source_offset: remark.position)
             @attached_spans << remark.position
           end
         end
       end
 
-      # Position-based fallback for finding containing scope.
-      # Used when scope map lookup returns nil (e.g., for remarks at lines
-      # outside any declared scope's end_line, or for non-scope-containers).
-      def find_containing_scope_position(remark_line, nodes_with_positions)
-        containing_nodes = nodes_with_positions.select do |n|
-          n[:line] && n[:end_line] && remark_line >= n[:line] && remark_line <= n[:end_line] &&
-            !repository?(n[:node]) && !cache?(n[:node])
-        end
+      # ----- Untagged remark attachment -----
+
+      def attach_untagged_remarks(remarks)
+        untagged = remarks.reject(&:tag)
+        return unless untagged.any?
+
+        untagged.each do |remark|
+          next if @attached_spans.include?(remark.position)
+
+          line_content = line_content_for(remark.line)
+          if end_scope_line?(line_content)
+            matched_node = @node_index.node_for_end_scope_at(remark.line, line_content)
+            if matched_node
+              add_remark(matched_node, remark.text, format: remark.format, tag: nil,
+                                                    source_offset: remark.position)
+              @attached_spans << remark.position
+              next
+            end
+          end
 
-        containing_nodes.reverse_each do |n|
-          node = n[:node]
-          return node if node.is_a?(Model::ScopeContainer)
+          target, placement, region = find_body_comment_target(remark)
+          if target
+            add_remark(target, remark.text, format: remark.format, tag: nil,
+                                            placement: placement, region: region)
+            @attached_spans << remark.position
+            next
+          end
+
+          matched_node = @node_index.nearest_node_to(remark.line)
+          if matched_node
+            add_remark(matched_node, remark.text, format: remark.format, tag: nil,
+                                                  source_offset: remark.position)
+            @attached_spans << remark.position
+          end
         end
+      end
 
-        nil
+      def end_scope_line?(line_content)
+        line_content =~ /END_(SCHEMA|ENTITY|TYPE|FUNCTION|PROCEDURE|RULE)/i
+      end
+
+      # Own-line body comments belong to the next statement in the same
+      # statement region (Function body, THEN branch, ELSE branch, loop body):
+      # attached there with LEADING placement. A comment with no following
+      # statement in its region closes that region, so it attaches to the
+      # region's owner with TRAILING placement and the region's name — an IF
+      # owns two bodies that close at different keywords.
+      #
+      # Returns [nil, nil, nil] — "use the legacy fallback" — when the remark
+      # shares a line with a node or sits outside any statement-bearing node.
+      def find_body_comment_target(remark)
+        line = remark.line
+        nodes = @node_index.nodes
+        # An own-line comment shares its line with no node. A node STARTING
+        # here means the remark is an inline tail (code; -- note). The
+        # end-line check is restricted to statements: container end_lines are
+        # child-derived approximations that can collide with comment lines.
+        return inline_target(remark, nodes) if inline_remark?(remark)
+
+        # A closing keyword on the next code line is decisive: the comment
+        # closes that body. Without this check the comment would instead be
+        # read as leading the next statement of an OUTER region, which is
+        # where it would wrongly render.
+        closing = closing_region_target(line, nodes)
+        return closing if closing.first
+
+        enclosing, region, = statement_region_for(line, nodes)
+        return [nil, nil, nil] unless region
+
+        following = region
+          .select { |n| n[:line] > line }
+          .min_by { |n| n[:position] }
+        if following
+          return [following[:node], Model::RemarkPlacement::LEADING, nil]
+        end
+
+        # No following statement and no closing keyword above: the comment is
+        # not demonstrably inside this body (it may sit after the whole
+        # declaration). Keep the legacy attachment rather than guessing.
+        [enclosing[:node], nil, nil]
+      end
+
+      # Whether the remark trails code on its own line. Decided from the
+      # source text before it, not from node positions: container end lines
+      # are child-derived approximations that collide with comment lines and
+      # would misread an own-line comment as a trailing one.
+      def inline_remark?(remark)
+        content = line_content_for(remark.line).to_s
+        opener = content.index("--")
+        return false unless opener
+
+        !content[0...opener].strip.empty?
+      end
+
+      # A comment trailing code on its line belongs to the statement that
+      # ends closest before it: `x := 1; -- why`. Only single-line statements
+      # qualify, because appending to a statement spanning several lines
+      # would move the remark down to its closing keyword.
+      def inline_target(remark, nodes)
+        owner = nodes
+          .select do |n|
+            n[:node].is_a?(Model::Statement) &&
+              n[:line] == remark.line && n[:end_line] == remark.line &&
+              n[:position] && n[:position] < remark.position
+          end
+          .max_by { |n| n[:position] + n[:node].source.to_s.length }
+        return [nil, nil, nil] unless owner
+
+        [owner[:node], Model::RemarkPlacement::INLINE, nil]
+      end
+
+      # Which closing keyword ends which region of which owner. A comment
+      # sitting between a body's last statement and one of these keywords
+      # closes that body.
+      CLOSING_KEYWORDS = {
+        /\AELSE\b/i => [Model::Statements::If, :statements],
+        /\AEND_IF\b/i => [Model::Statements::If, :else_statements],
+        /\AOTHERWISE\b/i => [Model::Statements::Case, :action_statements],
+        /\AEND_CASE\b/i => [Model::Statements::Case, :otherwise_statements],
+        /\AEND_REPEAT\b/i => [Model::Statements::Repeat, :statements],
+        /\AEND_ALIAS\b/i => [Model::Statements::Alias, :statements],
+        /\AEND\s*;/i => [Model::Statements::Compound, :statements],
+        # A RULE's executable body ends at WHERE, not at END_RULE.
+        /\AWHERE\b/i => [Model::Declarations::Rule, :statements],
+        /\AEND_FUNCTION\b/i => [Model::Declarations::Function, :statements],
+        /\AEND_PROCEDURE\b/i => [Model::Declarations::Procedure, :statements],
+        # END_RULE closes the WHERE section when the rule has one.
+        /\AEND_RULE\b/i => [Model::Declarations::Rule, :where_rules],
+      }.freeze
+
+      # Regions whose owner may not have that body, in which case the
+      # keyword closes the earlier region instead.
+      REGION_FALLBACKS = {
+        [Model::Statements::If, :else_statements] =>
+          [:statements, ->(n) { n.else_statements&.length&.positive? }],
+        [Model::Statements::Case, :otherwise_statements] =>
+          [:action_statements, ->(n) { !n.otherwise_statement.nil? }],
+        [Model::Declarations::Rule, :where_rules] =>
+          [:statements, ->(n) { n.where_rules&.length&.positive? }],
+      }.freeze
+
+      # A node's indexed span stops at its last child, so a comment written
+      # after that child but before the node's closing keyword sits outside
+      # every span and never reaches statement_region_for. Resolve it from
+      # the keyword that follows: it names both the owner type and the body
+      # being closed.
+      def closing_region_target(line, nodes)
+        keyword_owner, region, keyword_line = closing_keyword_after(line)
+        return [nil, nil, nil] unless keyword_owner
+
+        # The owner is the construct the keyword actually closes — the
+        # innermost one still open at that line. Picking the latest node of
+        # the right class instead would grab an already-closed inner block
+        # (nested IFs) or an unrelated earlier declaration (a RULE, when the
+        # WHERE really belongs to an ENTITY).
+        opener_line = active_opener_line(keyword_line, keyword_owner)
+        return [nil, nil, nil] unless opener_line
+
+        owner = nodes.find do |n|
+          n[:node].is_a?(keyword_owner) && n[:line] == opener_line
+        end
+        return [nil, nil, nil] unless owner
+
+        # END_IF closes the THEN body when there is no ELSE; END_CASE closes
+        # the last action when there is no OTHERWISE.
+        fallback, present = REGION_FALLBACKS[[keyword_owner, region]]
+        region = fallback if fallback && !present.call(owner[:node])
+
+        [owner[:node], Model::RemarkPlacement::TRAILING, region.to_s]
       end
 
-      # Done once per RemarkAttacher instance (O(file_lines)).
-      # Each find_containing_scope call then becomes O(1).
-      def build_scope_map
-        lines = source_lines
-        scope_map = {}
-        return scope_map if lines.empty?
+      # The first non-blank, non-comment source line after `line`.
+      # Source keywords that open a nestable construct, paired with the class
+      # of node they produce. Used to find which construct a closing keyword
+      # actually belongs to.
+      OPENERS = [
+        [/\bIF\b.*?\bTHEN\b/i, Model::Statements::If],
+        [/\bCASE\b.*?\bOF\b/i, Model::Statements::Case],
+        [/\bREPEAT\b/i, Model::Statements::Repeat],
+        [/\bALIAS\b/i, Model::Statements::Alias],
+        [/\bBEGIN\b/i, Model::Statements::Compound],
+        [/\A\s*FUNCTION\b/i, Model::Declarations::Function],
+        [/\A\s*PROCEDURE\b/i, Model::Declarations::Procedure],
+        [/\A\s*RULE\b/i, Model::Declarations::Rule],
+        [/\A\s*ENTITY\b/i, :other],
+        [/\A\s*TYPE\b/i, :other],
+      ].freeze
 
-        # Track nested scopes by scanning all lines once
-        scope_stack = [] # array of {type:, name:, line:}
+      CLOSERS = /\bEND_IF\b|\bEND_CASE\b|\bEND_REPEAT\b|\bEND_ALIAS\b|\bEND_FUNCTION\b|\bEND_PROCEDURE\b|\bEND_RULE\b|\bEND_ENTITY\b|\bEND_TYPE\b|\bEND\s*;/i
 
-        lines.each_with_index do |line, idx|
-          line_num = idx + 1
+      # Strips what must not be scanned for keywords: string literals and a
+      # trailing `--` remark. Without this, `x := 'IF a THEN'` or a comment
+      # mentioning REPEAT would push a construct that never opened.
+      def keyword_scannable(content)
+        without_strings = content.gsub(/'[^']*'/, "''")
+        tail = without_strings.index("--")
+        tail ? without_strings[0...tail] : without_strings
+      end
 
-          # Check for START keywords first
-          if line =~ /^\s*SCHEMA\s+(\w+)/i
-            scope_stack << { type: :schema, name: $1, line: line_num }
-          end
+      # The opening line of the innermost construct still open at
+      # `keyword_line`, or nil when that construct is not of `expected_class`.
+      def active_opener_line(keyword_line, expected_class)
+        active = active_scope_map[keyword_line]
+        return nil unless active && active[0] == expected_class
 
-          if line =~ /^\s*FUNCTION\s+(\w+)/i
-            scope_stack << { type: :function, name: $1, line: line_num }
-          end
+        active[1]
+      end
 
-          if line =~ /^\s*PROCEDURE\s+(\w+)/i
-            scope_stack << { type: :procedure, name: $1, line: line_num }
-          end
+      # Line number => the construct open at the START of that line, as
+      # [class, opening_line]. Built once per source: rescanning from line 1
+      # for every trailing comment is quadratic, and on a comment-dense file
+      # that cost dominates parsing entirely.
+      def active_scope_map
+        @active_scope_map ||= build_active_scope_map
+      end
 
-          if line =~ /^\s*RULE\s+(\w+)/i
-            scope_stack << { type: :rule, name: $1, line: line_num }
-          end
+      def build_active_scope_map
+        map = {}
+        stack = []
+        (1..source_line_count).each do |ln|
+          map[ln] = stack.last
+          content = keyword_scannable(line_content_for(ln).to_s.strip)
+          next if content.empty? || content.start_with?("--")
 
-          if line =~ /^\s*ENTITY\s+(\w+)/i
-            scope_stack << { type: :entity, name: $1, line: line_num }
+          line_events(content).each do |_offset, kind, klass|
+            kind == :open ? stack << [klass, ln] : stack.pop
           end
+        end
+        map
+      end
 
-          if line =~ /^\s*TYPE\s+(\w+)/i
-            scope_stack << { type: :type, name: $1, line: line_num }
+      # Opener/closer events on one line, ordered by where they appear.
+      # EVERY occurrence is collected, not just the first: a line holding two
+      # complete IF blocks contributes two openers and two closers, and
+      # recording only one opener would over-pop the enclosing construct.
+      def line_events(content)
+        events = []
+        OPENERS.each do |pattern, klass|
+          content.enum_for(:scan, pattern).each do
+            events << [Regexp.last_match.begin(0), :open, klass]
           end
+        end
+        content.enum_for(:scan, CLOSERS).each do
+          events << [Regexp.last_match.begin(0), :close, nil]
+        end
+        events.sort_by(&:first)
+      end
 
-          # Check for END keywords (inline closures on same line handled here)
-          if (line =~ /END_TYPE/i) && (scope_stack.last&.dig(:type) == :type)
-            scope_stack.pop
-          end
-          if (line =~ /END_FUNCTION/i) && (scope_stack.last&.dig(:type) == :function)
-            scope_stack.pop
-          end
-          if (line =~ /END_PROCEDURE/i) && (scope_stack.last&.dig(:type) == :procedure)
-            scope_stack.pop
-          end
-          if (line =~ /END_RULE/i) && (scope_stack.last&.dig(:type) == :rule)
-            scope_stack.pop
-          end
-          if (line =~ /END_ENTITY/i) && (scope_stack.last&.dig(:type) == :entity)
-            scope_stack.pop
-          end
-          if (line =~ /END_SCHEMA/i) && (scope_stack.last&.dig(:type) == :schema)
-            scope_stack.pop
-          end
+      def closing_keyword_after(line)
+        probe = line + 1
+        # Skip further comment lines AND blank lines: a comment separated
+        # from its closing keyword by an empty line still closes that body.
+        while probe <= source_line_count
+          content = line_content_for(probe).to_s.strip
+          break unless content.empty? || content.start_with?("--")
 
-          # Record the innermost scope for this line
-          scope_map[line_num] = scope_stack.last&.dig(:name)
+          probe += 1
+        end
+        content = line_content_for(probe).to_s.strip
+        CLOSING_KEYWORDS.each do |pattern, owner_region|
+          return [*owner_region, probe] if content.match?(pattern)
         end
+        [nil, nil, nil]
+      end
 
-        scope_map
+      def statement_region_for(line, nodes)
+        candidates = nodes.select do |n|
+          n[:line] && n[:end_line] && n[:line] <= line && n[:end_line] >= line &&
+            (n[:node].is_a?(Model::Statement) || function_rule_procedure?(n[:node]))
+        end
+        enclosing = innermost_candidate(candidates)
+        return [nil, nil, nil] unless enclosing
+
+        children = nodes.select do |n|
+          n[:owner].equal?(enclosing[:node]) &&
+            STATEMENT_REGIONS.include?(n[:collection]) && n[:line]
+        end
+        return [enclosing, nil, nil] if children.empty?
+
+        preceding = children.select { |n| n[:line] < line }.max_by { |n| n[:position] }
+        following = children.select { |n| n[:line] > line }.min_by { |n| n[:position] }
+        region_attr = region_attr_for(line, preceding, following)
+        return [enclosing, nil, nil] unless region_attr
+
+        [enclosing, children.select { |n| n[:collection] == region_attr }, region_attr]
       end
 
-      # O(1) scope lookup using pre-computed scope map
-      def find_containing_scope_by_name(remark_line)
-        return nil unless @scope_map
+      # Node end lines are child-derived approximations, so a parent's span
+      # can come out SMALLER than a child's and span size alone picks the
+      # wrong container. Ownership links are exact: drop every candidate
+      # that is an ancestor of another candidate, then pick the smallest
+      # span among the true leaves.
+      def innermost_candidate(candidates)
+        return candidates.first if candidates.length <= 1
+
+        owner_of = owner_map
+        ancestors = Set.new.compare_by_identity
+        candidates.each do |cand|
+          current = owner_of[cand[:node]]
+          while current
+            ancestors << current
+            current = owner_of[current]
+          end
+        end
 
-        scope_name = @scope_map[remark_line]
-        return nil unless scope_name
+        leaves = candidates.reject { |n| ancestors.include?(n[:node]) }
+        (leaves.empty? ? candidates : leaves).min_by { |n| n[:end_line] - n[:line] }
+      end
 
-        # Find the model node for this scope
-        return nil unless @model
+      # The node index is immutable during attachment, so its ownership map
+      # only needs to be built once for all body remarks.
+      def owner_map
+        # Identity comparison must be enabled BEFORE the hash is populated.
+        # Model elements compare by value, so two distinct-but-equal nodes
+        # would collapse into one entry during a plain build, and switching
+        # to identity afterwards cannot recover the lost entry.
+        @owner_map ||= @node_index.nodes.each_with_object(
+          {}.compare_by_identity,
+        ) { |n, map| map[n[:node]] = n[:owner] }
+      end
 
-        @model.schemas.each do |schema|
-          return schema if schema.id == scope_name
+      # The keyword that opens each region, for regions that follow another
+      # region of the same owner. A comment in the gap belongs to whichever
+      # side of this keyword it was written on.
+      REGION_OPENERS = {
+        else_statements: /\A(?:.*;)?\s*ELSE(?:\s*--.*)?\z/i,
+        otherwise_statements: /\A\s*OTHERWISE\b/i,
+      }.freeze
 
-          %i[functions procedures rules entities types].each do |decl_type|
-            collection = schema.public_send(decl_type)
-            next unless collection.is_a?(Array)
+      # A comment between two regions of the same owner — between the THEN
+      # body and ELSE, or between the last CASE action and OTHERWISE — sits
+      # on one side of the keyword that opens the second region. The gap can
+      # hold only that keyword and comments, so scanning it is exact.
+      # Comment lines are skipped so prose mentioning the keyword cannot
+      # match.
+      def region_attr_for(line, preceding, following)
+        return following&.dig(:collection) unless preceding
 
-            found = collection.find { |n| n.id == scope_name }
-            return found if found
+        following_attr = following&.dig(:collection)
+        opener = REGION_OPENERS[following_attr]
+        if opener && following_attr != preceding[:collection]
+          opener_line = (preceding[:end_line]...following[:line]).find do |ln|
+            content = line_content_for(ln).strip
+            !content.start_with?("--") && opener.match?(content)
           end
+          return following_attr if opener_line && line > opener_line
         end
 
-        nil
+        preceding[:collection]
       end
 
+      # ----- Tag resolution (within a scope) -----
+
       def find_node_in_scope(scope, tag)
         return nil unless scope
 
@@ -338,20 +556,17 @@ module Expressir
           end
         end
 
-        # Search inside types for enumeration items
         types = get_collection(scope, :types)
         types&.each do |type|
           result = find_enumeration_item_in_type(type, tag)
           return result if result
         end
 
-        # Search inside statements for nested items (alias, repeat, query)
         statements = get_collection(scope, :statements)
         statements&.each do |stmt|
           result = find_node_in_statement(stmt, tag)
           return result if result
 
-          # Search inside expressions for QueryExpression (nested in assignments, etc.)
           result = find_query_in_expression(stmt, tag)
           return result if result
         end
@@ -361,45 +576,19 @@ module Expressir
 
       def find_enumeration_item_in_type(type, tag)
         return nil unless type
+        return nil unless type.is_a?(Model::Declarations::Type)
 
-        # Check if type is a Type declaration with enumeration
-        if type.is_a?(Model::Declarations::Type)
-          # Check enumeration_items on the type itself
-          type.enumeration_items&.each do |item|
-            return item if item.id == tag
-          end
-
-          # Also check underlying_type if it's an enumeration
-          ut = type.underlying_type
-          if ut.is_a?(Model::DataTypes::Enumeration) && ut.items
-            ut.items.each do |item|
-              return item if item.id == tag
-            end
-          end
+        type.enumeration_items&.each do |item|
+          return item if item.id == tag
         end
 
+        ut = type.underlying_type
+        return nil unless ut.is_a?(Model::DataTypes::Enumeration) && ut.items
+
+        ut.items.each { |item| return item if item.id == tag }
         nil
       end
 
-      # Expression and statement child attributes for QueryExpression search.
-      # Targeted traversal prevents over-matching on unrelated model attributes.
-      EXPRESSION_CHILDREN = {
-        Model::Expressions::BinaryExpression => %i[operand1 operand2],
-        Model::Expressions::UnaryExpression => %i[operand],
-        Model::Expressions::QueryExpression => %i[expression aggregate_source],
-        Model::Expressions::AggregateInitializerItem => %i[expression
-                                                           repetition],
-        Model::Expressions::Interval => %i[low item high],
-        Model::Expressions::FunctionCall => %i[parameters],
-        Model::Expressions::EntityConstructor => %i[parameters],
-        Model::Expressions::AggregateInitializer => %i[items],
-        Model::Statements::Assignment => %i[expression],
-        Model::Statements::If => %i[expression],
-        Model::Statements::Case => %i[expression],
-        Model::Statements::CaseAction => %i[expression],
-        Model::Statements::Repeat => %i[while_expression until_expression],
-      }.freeze
-
       def find_query_in_expression(node, tag, visited = Set.new)
         return nil unless node
         return nil unless node.is_a?(Model::ModelElement)
@@ -407,9 +596,7 @@ module Expressir
 
         visited.add(node.object_id)
 
-        if node.is_a?(Model::Expressions::QueryExpression) && node.id == tag
-          return node
-        end
+        return node if node.is_a?(Model::Expressions::QueryExpression) && node.id == tag
 
         attrs = EXPRESSION_CHILDREN[node.class]
         return nil unless attrs
@@ -446,7 +633,6 @@ module Expressir
         prefix, id = tag.split(":")
         return nil unless id
 
-        # Determine collection based on prefix
         collection_attr = case prefix.downcase
                           when "wr" then :where_rules
                           when "ip" then :informal_propositions
@@ -454,14 +640,12 @@ module Expressir
                           end
         return nil unless collection_attr
 
-        # First try to find in containing scope
         collection = get_collection(containing_scope, collection_attr)
         if collection
           found = collection.find { |item| item.is_a?(Model::ModelElement) && item.id == id }
           return found if found
         end
 
-        # Fallback: try to find by full path
         schema_ids.each do |schema_id|
           full_path = "#{schema_id}.#{tag.tr(':', '.')}"
           found = safe_find(model, full_path)
@@ -471,38 +655,50 @@ module Expressir
         nil
       end
 
-      # Find target for remarks inside WHERE clauses
+      # Find target for remarks inside WHERE clauses by scanning source lines
+      # for `WHERE <id>:` patterns. Lives here (not in ScopeResolver) because
+      # it's about WHERE-rule membership, not scope membership.
       def find_target_in_where_clause(scope, tag, remark_line)
         return nil unless supports_where_rules?(scope)
 
         where_rules = get_collection(scope, :where_rules)
         return nil unless where_rules&.any?
 
-        # Search source text for WHERE clause containing this remark
-        lines = source_lines
+        where_clause_lines = where_clause_line_index
 
         where_rules.each do |wr|
           next unless wr.id
 
-          # Find the WHERE rule declaration
-          lines.each_with_index do |line, idx|
-            line_num = idx + 1
+          where_clause_lines.fetch(wr.id, []).each do |line_num|
             next unless line_num < remark_line
 
-            # Look for "WHERE {id}:" pattern
-            # Check if remark is within a few lines after this WHERE declaration
-            if (line =~ /^\s*WHERE\s+#{Regexp.escape(wr.id)}\s*:/i) && remark_line.between?(
-              line_num, line_num + 5
-            )
-              # Found the WHERE rule - create remark item inside it
-              return create_remark_item(wr, tag)
-            end
+            return create_remark_item(wr, tag) if remark_line.between?(line_num, line_num + 5)
           end
         end
 
         nil
       end
 
+      # Single scan over the source lines mapping each `WHERE <id>:` label to
+      # its 1-based line number, so per-remark lookups stop re-testing every
+      # line against every WHERE rule's regex.
+      def where_clause_line_index
+        @where_clause_line_index ||= begin
+          index = Hash.new { |h, k| h[k] = [] }
+          source_lines_for_where_clause.each_with_index do |line, idx|
+            if (match = line.match(WHERE_CLAUSE_PATTERN))
+              index[match[1]] << (idx + 1)
+            end
+          end
+          index
+        end
+      end
+
+      def source_lines_for_where_clause
+        # @source is set for the duration of `attach`; freed at the end.
+        @source_lines_for_where_clause ||= @source.lines
+      end
+
       def find_node_in_statement(stmt, tag)
         case stmt
         when Model::Statements::Alias
@@ -515,15 +711,6 @@ module Expressir
         nil
       end
 
-      def find_containing_scope(remark_line, nodes_with_positions)
-        # First try scope map (O(1) once built)
-        scope = find_containing_scope_by_name(remark_line)
-        return scope if scope
-
-        # Fallback to position-based detection
-        find_containing_scope_position(remark_line, nodes_with_positions)
-      end
-
       def build_scope_path(node)
         return nil unless node
 
@@ -535,7 +722,6 @@ module Expressir
             parts.unshift(current.id)
           end
 
-          # Stop at schema level
           break if current.is_a?(Model::Declarations::Schema)
 
           current = current.parent
@@ -544,113 +730,33 @@ module Expressir
         parts.empty? ? nil : parts.join(".")
       end
 
-      def find_scope_by_source_text(remark_line)
-        # Search backwards from remark_line for containing scope
-        lines = source_lines
-
-        # Find the entity/type/rule that contains this line
-        entity_start = nil
-        type_start = nil
-        rule_start = nil
-        current_entity = nil
-        current_type = nil
-        current_rule = nil
-
-        lines.each_with_index do |line, idx|
-          line_num = idx + 1
-
-          case line
-          when /^\s*ENTITY\s+(\w+)/i
-            entity_start = line_num
-            current_entity = $1
-          when /^\s*END_ENTITY/i
-            if entity_start && remark_line >= entity_start && remark_line <= line_num
-              # Found containing entity
-              return find_node_by_type_and_name(Model::Declarations::Entity,
-                                                current_entity)
-            end
-
-            entity_start = nil
-            current_entity = nil
-          when /^\s*TYPE\s+(\w+)/i
-            type_start = line_num
-            current_type = $1
-          when /^\s*END_TYPE/i
-            if type_start && remark_line >= type_start && remark_line <= line_num
-              # Found containing type
-              return find_node_by_type_and_name(Model::Declarations::Type,
-                                                current_type)
-            end
-
-            type_start = nil
-            current_type = nil
-          when /^\s*RULE\s+(\w+)/i
-            rule_start = line_num
-            current_rule = $1
-          when /^\s*END_RULE/i
-            if rule_start && remark_line >= rule_start && remark_line <= line_num
-              # Found containing rule
-              return find_node_by_type_and_name(Model::Declarations::Rule,
-                                                current_rule)
-            end
-
-            rule_start = nil
-            current_rule = nil
-          end
-        end
-
-        nil
-      end
-
-      COLLECTION_ACCESSOR = {
-        Expressir::Model::Declarations::Entity => lambda(&:entities),
-        Expressir::Model::Declarations::Type => lambda(&:types),
-        Expressir::Model::Declarations::Rule => lambda(&:rules),
-      }.freeze
-
-      def find_node_by_type_and_name(node_class, name)
-        return nil unless @model && name
-
-        accessor = COLLECTION_ACCESSOR[node_class]
-        return nil unless accessor
-
-        @model.schemas.each do |schema|
-          found = accessor.call(schema)&.find { |n| n.id == name }
-          return found if found
-        end
-
-        nil
-      end
+      # ----- Path-based lookup -----
 
       def find_by_exact_path(model, path)
         return nil unless path
-
-        # Only Repository and ExpFile support path-based find
         return nil unless repository?(model) || exp_file?(model)
 
-        # Try original path
         result = safe_find(model, path)
         return result if result
 
-        # Try with colon converted to dot
         normalized = path.tr(":", ".")
         normalized == path ? nil : safe_find(model, normalized)
       end
 
+      # ----- Target creation -----
+
       def create_implicit_remark_item_at_schema(model, item_id, schema_id)
-        # Only Repository and ExpFile support schema lookup
         return nil unless repository?(model) || exp_file?(model)
 
         schema = safe_find(model, schema_id)
         return nil unless schema.is_a?(Model::Declarations::Schema)
 
-        # Handle informal propositions (IP\d+ pattern) - only if schema supports it
-        # Note: Schema doesn't have informal_propositions, so this will create a remark_item instead
-        if item_id.match?(/^IP\d+$/) && supports_informal_propositions?(schema)
-          return create_or_find_informal_proposition(schema, item_id)
+        # Strip "wr:" prefix convention (e.g. "wr:IP1" → "IP1")
+        ip_id = extract_ip_id(item_id)
+        if ip_id && supports_informal_propositions?(schema)
+          return create_or_find_informal_proposition(schema, ip_id)
         end
 
-        # Handle remark items
         return nil unless supports_remark_items?(schema)
 
         existing = schema.remark_items&.find { |ri| ri.id == item_id }
@@ -662,19 +768,35 @@ module Expressir
       def create_implicit_remark_item(model, path, schema_ids = [])
         return nil unless repository?(model) || exp_file?(model)
 
-        # Normalize path (handle "ip:IP1" format)
+        # Handle "wr:IP1" convention: extract parent path and IP id directly
+        # so normalize_path doesn't split "wr:IP1" into "wr"."IP1" segments.
+        ip_prefix_match = path.match(/\A(.+)\.(\w+):(IP\d+)\z/)
+        if ip_prefix_match
+          parent_path = ip_prefix_match[1]
+          ip_id = ip_prefix_match[3]
+          parent = safe_find(model, parent_path)
+          if parent.nil? && schema_ids.any?
+            schema_ids.each do |schema_id|
+              parent = safe_find(model, "#{schema_id}.#{parent_path}")
+              break if parent
+            end
+          end
+
+          if parent && supports_informal_propositions?(parent)
+            return create_or_find_informal_proposition(parent, ip_id)
+          end
+        end
+
         clean_path = normalize_path(path)
         parts = clean_path.split(".")
         return nil if parts.length < 2
 
-        # Find the deepest existing parent and create item there
         (parts.length - 1).downto(1) do |i|
           parent_path = parts[0...i].join(".")
           item_id = parts[i]
 
           parent = safe_find(model, parent_path)
 
-          # Try with schema prefix if not found
           if parent.nil? && schema_ids.any?
             schema_ids.each do |schema_id|
               parent = safe_find(model, "#{schema_id}.#{parent_path}")
@@ -698,12 +820,12 @@ module Expressir
       end
 
       def create_item_at_parent(parent, item_id)
-        # Handle informal propositions
-        if item_id.match?(/^IP\d+$/) && supports_informal_propositions?(parent)
-          return create_or_find_informal_proposition(parent, item_id)
+        # Strip "wr:" prefix convention (e.g. "wr:IP1" → "IP1")
+        ip_id = extract_ip_id(item_id)
+        if ip_id && supports_informal_propositions?(parent)
+          return create_or_find_informal_proposition(parent, ip_id)
         end
 
-        # Handle remark items
         return nil unless supports_remark_items?(parent)
 
         existing = parent.remark_items&.find { |ri| ri.id == item_id }
@@ -713,7 +835,6 @@ module Expressir
       end
 
       def create_or_find_informal_proposition(parent, id)
-        # Only Entity, Rule, Type, and InformalPropositionRule have informal_propositions
         return nil unless supports_informal_propositions?(parent)
 
         existing = parent.informal_propositions&.find { |ip| ip.id == id }
@@ -725,15 +846,12 @@ module Expressir
         parent.informal_propositions << ip
         safe_reset_children_by_id(parent)
 
-        # Also create a RemarkItem inside the InformalPropositionRule
-        # This is the expected structure for informal proposition remarks
         remark_item = Model::Declarations::RemarkItem.new(id: id)
         remark_item.parent = ip
         ip.remark_items ||= []
         ip.remark_items << remark_item
         safe_reset_children_by_id(ip)
 
-        # Return the remark_item so remarks are added to it
         remark_item
       end
 
@@ -746,92 +864,32 @@ module Expressir
         item
       end
 
-      def attach_untagged_remarks(remarks, nodes_with_positions)
-        untagged = remarks.reject(&:tag)
-        return unless untagged.any?
-
-        untagged.each do |remark|
-          next if @attached_spans.include?(remark.position)
-
-          if end_scope_line?(remark.line)
-            matched_node = find_node_for_end_scope_remark(remark,
-                                                          nodes_with_positions)
-            if matched_node
-              add_remark(matched_node, remark.text, format: remark.format, tag: nil)
-              @attached_spans << remark.position
-              next
-            end
-          end
-
-          matched_node = find_nearest_node(remark, nodes_with_positions)
-          if matched_node
-            add_remark(matched_node, remark.text, format: remark.format, tag: nil)
-            @attached_spans << remark.position
-          end
-        end
-      end
-
-      def end_scope_line?(line_num)
-        line = get_line_content(line_num)
-        line =~ /END_(SCHEMA|ENTITY|TYPE|FUNCTION|PROCEDURE|RULE)/i
-      end
-
-      def get_line_content(line_num)
-        lines = source_lines
-        return "" if line_num < 1 || line_num > lines.length
-
-        lines[line_num - 1]
-      end
-
-      def find_node_for_end_scope_remark(remark, nodes)
-        line_content = get_line_content(remark.line)
-
-        node_type = case line_content
-                    when /END_SCHEMA/i then Model::Declarations::Schema
-                    when /END_ENTITY/i then Model::Declarations::Entity
-                    when /END_TYPE/i then Model::Declarations::Type
-                    when /END_FUNCTION/i then Model::Declarations::Function
-                    when /END_PROCEDURE/i then Model::Declarations::Procedure
-                    when /END_RULE/i then Model::Declarations::Rule
-                    end
-
-        return nil unless node_type
-
-        matching_nodes = nodes.select do |n|
-          n[:node].is_a?(node_type) &&
-            (n[:end_line] == remark.line ||
-             (n[:end_line] && n[:end_line] <= remark.line && n[:end_line] >= remark.line - 2))
-        end
-
-        matching_nodes.first&.dig(:node) || find_node_by_type(nodes, node_type)
-      end
-
-      def find_node_by_type(nodes, node_type)
-        nodes.find { |n| n[:node].is_a?(node_type) }&.dig(:node)
-      end
+      # ----- Remark storage -----
 
-      def add_remark(node, text, format: "tail", tag: nil)
+      def add_remark(node, text, format: Model::RemarkFormat::TAIL, tag: nil,
+                     placement: nil, region: nil, source_offset: nil)
         return unless node
         return unless node.is_a?(Model::ModelElement)
 
-        # Only add remarks to nodes that support them
         if supports_remarks?(node)
-          # Always add to remarks attribute (for types that have it)
           if node_has_remarks?(node)
             node.remarks ||= []
             node.remarks << text
           end
 
           if tag.nil?
-            # Untagged remark: store in untagged_remarks
-            remark_info = Model::RemarkInfo.new(text: text, format: format)
+            remark_info = Model::RemarkInfo.new(text: text, format: format,
+                                                placement: placement,
+                                                region: region,
+                                                source_offset: source_offset)
             node.untagged_remarks ||= []
             node.untagged_remarks << remark_info
           end
         end
       end
 
-      # All ModelElement subclasses have untagged_remarks from ModelElement
+      # ----- Type predicates -----
+
       def supports_remarks?(obj)
         obj.is_a?(Model::ModelElement)
       end
@@ -840,180 +898,23 @@ module Expressir
         obj.is_a?(Model::HasRemarks)
       end
 
-      # Types that include HasRemarkItems can have remark_items
       def supports_remark_items?(obj)
         obj.is_a?(Model::HasRemarkItems)
       end
 
-      def collect_nodes_with_positions(node, result, visited = Set.new)
-        return unless node
-        return if visited.include?(node.object_id)
-
-        visited.add(node.object_id)
-
-        if node.is_a?(Model::ModelElement) && node.source
-          # Use stored source_offset from parser
-          # The parser always provides this via Slice#offset
-          if node.source_offset
-            pos = node.source_offset
-            # Validate offset: native parser returns 0 for leaf nodes (WhereRule)
-            # where it can't determine the actual position. These have short
-            # expression-like source ("TRUE;") that doesn't appear at file start.
-            # Container nodes (Schema, Entity, Type) have declaration-like source
-            # that either starts at position 0 legitimately or is clearly valid.
-            valid = pos.positive?
-            if !valid && pos.zero? && node.source
-              src = node.source.to_s
-              # Accept position=0 if source is a declaration keyword line
-              valid = src.start_with?("SCHEMA", "ENTITY", "TYPE", "FUNCTION",
-                                      "PROCEDURE", "RULE", "CONSTANT", "VARIABLE",
-                                      "USE", "REFERENCE", "END_SCHEMA", "END_ENTITY",
-                                      "END_TYPE", "END_FUNCTION", "END_PROCEDURE",
-                                      "END_RULE", "END_CONSTANT", "END_VARIABLE")
-            end
-            if valid
-              line = get_line_number(pos)
-              source_end_line = get_line_number(pos + node.source.length)
-
-              # For container nodes, use the maximum end_line from children
-              # This is needed because source.length only covers the declaration, not the body
-              children_end_line = calculate_children_end_line(node)
-              end_line = [source_end_line,
-                          children_end_line].compact.max || source_end_line
-
-              result << {
-                node: node,
-                position: pos,
-                line: line,
-                end_line: end_line,
-              }
-            else
-              # Invalid offset — treat as unknown position
-              result << { node: node, position: nil, line: nil, end_line: nil }
-            end
-          else
-            # No source_offset available - should not happen if parser provides Slice
-            result << { node: node, position: nil, line: nil, end_line: nil }
-          end
-        else
-          result << { node: node, position: nil, line: nil, end_line: nil }
-        end
-
-        collect_children(node, result, visited)
-      end
-
-      # Calculate the end line from all children of a node
-      # This is needed for container nodes like schemas, entities, etc.
-      # where source.length only covers the declaration, not the body
-      def calculate_children_end_line(node)
-        children_end_lines = []
-
-        # Check computed children (Schema, ExpFile have a children method)
-        if node.is_a?(Model::Declarations::Schema)
-          Array(node.children).each do |child|
-            if child.is_a?(Model::ModelElement) && child.source_offset && child.source
-              children_end_lines << get_line_number(child.source_offset + child.source.length)
-            end
-          end
-        end
-
-        # Visit declared collections from type registry
-        collections_on(node).each do |collection|
-          collection.each do |child|
-            if child.is_a?(Model::ModelElement) && child.source_offset && child.source
-              children_end_lines << get_line_number(child.source_offset + child.source.length)
-            end
-          end
-        end
-
-        children_end_lines.max
-      end
-
-      def collect_children(node, result, visited)
-        if node.is_a?(Model::Declarations::Schema)
-          Array(node.children).each do |child|
-            collect_nodes_with_positions(child, result, visited)
-          end
-        end
-
-        collections_on(node).each do |collection|
-          collection.each do |item|
-            collect_nodes_with_positions(item, result, visited)
-          end
-        end
+      def supports_informal_propositions?(obj)
+        obj.is_a?(Model::HasInformalPropositions)
       end
 
-      # Build sorted nodes_with_positions ONCE for both tagged and untagged remark passes.
-      # This merges the two separate tree walks into one, cutting node visits in half.
-      def build_sorted_nodes_with_positions(model)
-        nodes_with_positions = []
-        collect_nodes_with_positions(model, nodes_with_positions)
-        # Stable sort: nil positions last, ties broken by insertion order
-        nodes_with_positions.sort_by!.with_index { |n, i| [n[:position] || Float::INFINITY, i] }
-        nodes_with_positions
+      # Extracts an IP id from a potentially prefixed item_id.
+      # "wr:IP1" → "IP1", "IP1" → "IP1", "WR1" → nil
+      def extract_ip_id(item_id)
+        bare = item_id.sub(/\A\w+:/, "")
+        bare.match?(/^IP\d+$/) ? bare : nil
       end
 
-      def find_nearest_node(remark, nodes)
-        remark_line = remark.line
-
-        # For tail remarks, prefer nodes that START on the same line
-        # This handles cases like: "attr : STRING; -- tail remark"
-        # Exclude Repository and Cache as they are not semantic scopes
-        same_start_line = nodes.select do |n|
-          n[:line] == remark_line &&
-            !repository?(n[:node]) && !cache?(n[:node])
-        end
-        return same_start_line.last[:node] if same_start_line.any?
-
-        # Also check nodes that END on the same line
-        same_end_line = nodes.select do |n|
-          n[:end_line] == remark_line &&
-            !repository?(n[:node]) && !cache?(n[:node])
-        end
-        return same_end_line.last[:node] if same_end_line.any?
-
-        # Find the node that CONTAINS this remark line
-        # This handles preamble remarks and embedded remarks
-        # Exclude Repository and Cache as they are not semantic scopes
-        # But include ExpFile for file-level preamble remarks
-        containing = nodes.select do |n|
-          n[:line] && n[:end_line] && n[:line] <= remark_line && n[:end_line] >= remark_line &&
-            !repository?(n[:node]) && !cache?(n[:node])
-        end
-
-        if containing.any?
-          # Prefer ExpFile for preamble remarks (before first schema)
-          # Otherwise return the most specific (smallest) containing node
-          exp_file_node = containing.find { |n| exp_file?(n[:node]) }
-          # If this is a preamble remark (before first schema line), use ExpFile
-          if exp_file_node
-            first_schema_line = exp_file_node[:node].schemas&.first&.source_offset
-            if first_schema_line && remark_line < get_line_number(first_schema_line)
-              return exp_file_node[:node]
-            end
-          end
-          # Sort by span size and return the smallest
-          containing.min_by { |n| n[:end_line] - n[:line] }[:node]
-        else
-          # Fallback: find the last node that ends before this line
-          before = nodes.select do |n|
-            n[:end_line] && n[:end_line] < remark_line &&
-              !repository?(n[:node]) && !cache?(n[:node])
-          end
-          before.max_by { |n| n[:end_line] }[:node] if before.any?
-        end
-      end
-
-      # Type checking helper methods
-
-      def get_schema_ids(model)
-        if repository?(model)
-          model.schemas.filter_map(&:id)
-        elsif exp_file?(model)
-          model.schemas.filter_map(&:id)
-        else
-          []
-        end
+      def supports_where_rules?(obj)
+        obj.is_a?(Model::HasWhereRules)
       end
 
       def repository?(obj)
@@ -1028,13 +929,15 @@ module Expressir
         obj.is_a?(Model::Cache)
       end
 
-      def supports_informal_propositions?(obj)
-        obj.is_a?(Model::HasInformalPropositions)
+      def get_schema_ids(model)
+        if repository?(model) || exp_file?(model)
+          model.schemas.filter_map(&:id)
+        else
+          []
+        end
       end
 
-      def supports_where_rules?(obj)
-        obj.is_a?(Model::HasWhereRules)
-      end
+      # ----- Collection access -----
 
       # Type-driven collection access — returns all collections for a node's type.
       def collections_on(node)
@@ -1055,6 +958,8 @@ module Expressir
         collection if collection.is_a?(Array)
       end
 
+      # ----- Helpers -----
+
       def safe_find(model, path)
         return nil unless model
 
@@ -1069,6 +974,17 @@ module Expressir
 
         obj.reset_children_by_id
       end
+
+      def line_content_for(line_num)
+        lines = source_lines_for_where_clause
+        return "" if line_num < 1 || line_num > lines.length
+
+        lines[line_num - 1]
+      end
+
+      def source_line_count
+        source_lines_for_where_clause.length
+      end
     end
   end
 end