ibex-runtime 0.2.0

data/lib/ibex/runtime/cst/editor.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "editing" unless defined?(Ibex::Runtime::CST::Editing)
+
+module Ibex
+  module Runtime
+    module CST
+      class EditConflictError < StandardError; end
+
+      # Applies multiple occurrence-addressed replacements in one path-copying pass.
+      class SyntaxEditor
+        # @rbs! type element = SyntaxNode | SyntaxToken
+        # @rbs! type green = GreenNode | GreenToken
+        # @rbs! type edit = [element, green]
+
+        # @rbs @root: SyntaxNode
+        # @rbs @edits: Array[edit]
+
+        # @rbs (SyntaxNode root) -> void
+        def initialize(root)
+          @root = root
+          @edits = []
+        end
+
+        # @rbs (element target, green | element replacement) -> self
+        def replace(target, replacement)
+          raise ArgumentError, "edit target belongs to a different root" unless target.root.equal?(@root)
+
+          green = Editing.green_element(replacement)
+          duplicate = @edits.find { |existing, _value| same_occurrence?(existing, target) }
+          if duplicate
+            raise EditConflictError, "the same syntax occurrence has conflicting replacements" unless
+              duplicate.fetch(1).equal?(green)
+
+            return self
+          end
+          return self if @edits.any? { |existing, _value| ancestor?(existing, target) }
+
+          @edits.reject! { |existing, _value| ancestor?(target, existing) }
+          @edits << [target, green]
+          self
+        end
+
+        # @rbs () -> SyntaxNode
+        def apply
+          green = apply_element(@root)
+          return @root if green.equal?(@root.green)
+          raise TypeError, "a syntax root must remain a GreenNode" unless green.is_a?(GreenNode)
+
+          Editing.red_root(@root, green)
+        end
+
+        private
+
+        # @rbs (element element) -> green
+        def apply_element(element)
+          replacement = @edits.find { |target, _green| same_occurrence?(target, element) }&.fetch(1)
+          return replacement if replacement
+          return element.green if element.is_a?(SyntaxToken)
+
+          changed = false
+          children = element.children.map do |child|
+            green = apply_element(child)
+            changed ||= !green.equal?(child.green)
+            green
+          end
+          return element.green unless changed
+
+          GreenNode.new(
+            kind: element.green.kind, children: children,
+            flags: element.green.intrinsic_flags, annotations: element.green.annotations
+          )
+        end
+
+        # @rbs (element possible_ancestor, element element) -> bool
+        def ancestor?(possible_ancestor, element)
+          parent = element.parent
+          while parent
+            return true if same_occurrence?(parent, possible_ancestor)
+
+            parent = parent.parent
+          end
+          false
+        end
+
+        # @rbs (element left, element right) -> bool
+        def same_occurrence?(left, right)
+          left.root.equal?(right.root) && left.green.equal?(right.green) && left.offset == right.offset
+        end
+      end
+    end
+  end
+end

data/lib/ibex/runtime/cst/green/builder.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "cache" unless defined?(Ibex::Runtime::CST::NodeCache)
+
+module Ibex
+  module Runtime
+    module CST
+      # LR bottom-up builder backed by a Green element stack.
+      # rubocop:disable Naming/PredicateMethod -- mutation methods report whether they found a target.
+      class GreenBuilder
+        # @rbs! type child = GreenNode | GreenToken
+        empty_trivia = [] # @type var empty_trivia: Array[GreenTrivia]
+        EMPTY_TRIVIA = empty_trivia.freeze #: Array[GreenTrivia]
+
+        # @rbs @kinds: Kind
+        # @rbs @cache: NodeCache
+        # @rbs @stack: Array[child]
+
+        # @rbs (kinds: Kind, ?cache: NodeCache) -> void
+        def initialize(kinds:, cache: NodeCache.new)
+          @kinds = kinds
+          @cache = cache
+          @stack = []
+        end
+
+        # @rbs (Integer kind, String text, ?leading: Array[GreenTrivia], ?trailing: Array[GreenTrivia],
+        #   ?flags: Integer) -> GreenToken
+        def token(kind, text, leading: EMPTY_TRIVIA, trailing: EMPTY_TRIVIA, flags: 0)
+          value = make_token(kind, text, leading: leading, trailing: trailing, flags: flags)
+          @stack << value
+          value
+        end
+
+        # Construct an interned token without changing the builder stack.
+        # @rbs (Integer kind, String text, ?leading: Array[GreenTrivia], ?trailing: Array[GreenTrivia],
+        #   ?flags: Integer) -> GreenToken
+        def make_token(kind, text, leading: EMPTY_TRIVIA, trailing: EMPTY_TRIVIA, flags: 0)
+          @cache.intern_token_fields(
+            kind: kind, text: text, leading: leading, trailing: trailing, flags: flags
+          )
+        end
+
+        # @rbs (Integer kind, Integer arity, ?flags: Integer) -> GreenNode
+        def node(kind, arity, flags: 0)
+          raise ArgumentError, "arity must be non-negative" if arity.negative?
+          raise ArgumentError, "green stack underflow" if arity > @stack.length
+
+          empty = [] #: Array[child]
+          children = arity.zero? ? empty : @stack.pop(arity)
+          value = @cache.intern_node(GreenNode.new(kind: kind, children: children, flags: flags))
+          @stack << value
+          value
+        end
+
+        # Push one already validated nonterminal without rebuilding its descendants.
+        # @rbs (GreenNode value) -> GreenNode
+        def subtree(value)
+          @stack << value
+          value
+        end
+
+        # @rbs (Integer expected_kind) -> GreenToken
+        def missing(expected_kind)
+          value = @cache.intern_token_fields(
+            kind: @kinds.fetch(:missing_token), text: "", expected_kind: expected_kind,
+            flags: Flags::CONTAINS_MISSING | Flags::SYNTHETIC
+          )
+          @stack << value
+          value
+        end
+
+        # @rbs (String text, ?leading: Array[GreenTrivia]) -> GreenToken
+        def lexical_error(text, leading: EMPTY_TRIVIA)
+          value = @cache.intern_token_fields(
+            kind: @kinds.fetch(:lexical_error_token), text: text, leading: leading,
+            flags: Flags::CONTAINS_ERROR
+          )
+          @stack << value
+          value
+        end
+
+        # Preserve popped and discarded Green elements in one error node.
+        # @rbs (Integer pop_count, ?skipped: Array[child]) -> GreenNode
+        def absorb_into_error(pop_count, skipped: [])
+          raise ArgumentError, "pop_count must be non-negative" if pop_count.negative?
+          raise ArgumentError, "green stack underflow" if pop_count > @stack.length
+
+          empty = [] #: Array[child]
+          popped = pop_count.zero? ? empty : @stack.pop(pop_count)
+          value = @cache.intern_node(
+            GreenNode.new(
+              kind: @kinds.fetch(:error_node), children: popped + skipped,
+              flags: Flags::CONTAINS_ERROR
+            )
+          )
+          @stack << value
+          value
+        end
+
+        # Wrap the completed start node and explicit EOF token.
+        # @rbs (GreenToken eof_token, ?incomplete: bool) -> GreenNode
+        def finish_source_file(eof_token, incomplete: false)
+          raise ArgumentError, "expected one completed start node" unless @stack.one?
+
+          flags = Flags::SYNTHETIC
+          flags |= Flags::INCOMPLETE_INPUT if incomplete
+          @cache.intern_node(
+            GreenNode.new(
+              kind: @kinds.fetch(:source_file), children: [@stack.fetch(0), eof_token],
+              flags: flags
+            )
+          )
+        end
+
+        # Preserve every available fragment when parsing terminates without a start node.
+        # @rbs (?Array[child] trailing, ?incomplete: bool) -> GreenNode
+        def finish_synthetic_root(trailing = [], incomplete: false)
+          flags = Flags::SYNTHETIC | Flags::CONTAINS_ERROR
+          flags |= Flags::INCOMPLETE_INPUT if incomplete
+          @cache.intern_node(
+            GreenNode.new(
+              kind: @kinds.fetch(:synthetic_root), children: @stack + trailing,
+              flags: flags
+            )
+          )
+        end
+
+        # Append discarded input to the most recent error node on the stack.
+        # @rbs (child skipped) -> bool
+        def append_to_last_error(skipped)
+          index = @stack.rindex { |element| element.is_a?(GreenNode) && element.kind == @kinds.fetch(:error_node) }
+          return false unless index
+
+          error = @stack.fetch(index)
+          return false unless error.is_a?(GreenNode)
+
+          @stack[index] = @cache.intern_node(
+            GreenNode.new(
+              kind: error.kind, children: error.children + [skipped],
+              flags: error.intrinsic_flags | Flags::CONTAINS_ERROR, annotations: error.annotations
+            )
+          )
+          true
+        end
+
+        # Path-copy the right edge to attach balanced trailing trivia.
+        # @rbs (Array[GreenTrivia] trivia) -> bool
+        def append_trailing_to_last_token(trivia)
+          return false if trivia.empty?
+
+          index = @stack.length - 1
+          while index >= 0
+            replacement = with_rightmost_trailing(@stack.fetch(index), trivia)
+            if replacement
+              @stack[index] = replacement
+              return true
+            end
+            index -= 1
+          end
+          false
+        end
+
+        # @rbs () -> Array[child]
+        def snapshot = @stack.dup
+
+        # @rbs (Array[child] elements) -> void
+        def restore(elements)
+          @stack = elements.dup
+        end
+
+        # @rbs () -> Integer
+        def size = @stack.length
+
+        # @rbs () -> Array[child]
+        def elements = @stack.dup.freeze
+
+        private
+
+        # @rbs (child element, Array[GreenTrivia] trivia) -> child?
+        def with_rightmost_trailing(element, trivia)
+          if element.is_a?(GreenToken)
+            combined_trailing = element.trailing.empty? ? trivia : element.trailing + trivia
+            return @cache.intern_token_fields(
+              kind: element.kind, text: element.text, leading: element.leading,
+              trailing: combined_trailing, flags: element.flags,
+              expected_kind: element.expected_kind
+            )
+          end
+          return if element.children.empty?
+
+          child = element.children.last
+          return unless child
+
+          replacement = with_rightmost_trailing(child, trivia)
+          return unless replacement
+
+          children = element.children.dup
+          children[-1] = replacement
+          @cache.intern_node(
+            GreenNode.new(
+              kind: element.kind, children: children, flags: element.intrinsic_flags,
+              annotations: element.annotations
+            )
+          )
+        end
+      end
+      # rubocop:enable Naming/PredicateMethod
+    end
+  end
+end

data/lib/ibex/runtime/cst/green/cache.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "node" unless defined?(Ibex::Runtime::CST::GreenNode)
+
+module Ibex
+  module Runtime
+    module CST
+      # Session-owned hash-consing cache for immutable Green elements.
+      class NodeCache
+        DEFAULT_NODE_ARITY_LIMIT = 3 #: Integer
+        DEFAULT_NODE_DESCENDANT_LIMIT = 32 #: Integer
+        empty_trivia = [] # @type var empty_trivia: Array[GreenTrivia]
+        EMPTY_TRIVIA = empty_trivia.freeze #: Array[GreenTrivia]
+
+        # @rbs @enabled: bool
+        # @rbs @node_arity_limit: Integer
+        # @rbs @node_descendant_limit: Integer
+        # @rbs @trivia: Hash[Integer, Array[GreenTrivia]]
+        # @rbs @tokens: Hash[Integer, Array[GreenToken]]
+        # @rbs @nodes: Hash[GreenNode, GreenNode]
+
+        # @rbs (?enabled: bool, ?node_arity_limit: Integer, ?node_descendant_limit: Integer) -> void
+        def initialize(
+          enabled: true, node_arity_limit: DEFAULT_NODE_ARITY_LIMIT,
+          node_descendant_limit: DEFAULT_NODE_DESCENDANT_LIMIT
+        )
+          raise ArgumentError, "node_arity_limit must be non-negative" if node_arity_limit.negative?
+          raise ArgumentError, "node_descendant_limit must be positive" unless node_descendant_limit.positive?
+
+          @enabled = enabled
+          @node_arity_limit = node_arity_limit
+          @node_descendant_limit = node_descendant_limit
+          @trivia = {}
+          @tokens = {}
+          @nodes = {}
+        end
+
+        # Intern trivia before constructing it, using byte-equivalent text within this session.
+        # @rbs (kind: Integer, text: String) -> GreenTrivia
+        def intern_trivia_fields(kind:, text:)
+          return GreenTrivia.new(kind: kind, text: text) unless @enabled
+
+          comparable_text = if text.encoding == Encoding::BINARY || text.ascii_only?
+                              text
+                            else
+                              text.b.freeze
+                            end
+          signature = kind.hash ^ comparable_text.hash
+          bucket = @trivia[signature]
+          existing = bucket&.find { |trivia| trivia.kind == kind && trivia.text == comparable_text }
+          return existing if existing
+
+          trivia = GreenTrivia.new(kind: kind, text: comparable_text)
+          (@trivia[signature] ||= []) << trivia
+          trivia
+        end
+
+        # @rbs (GreenToken token) -> GreenToken
+        def intern_token(token)
+          return token unless @enabled
+          return token unless token.flags.nobits?(Flags::HAS_ANNOTATION)
+
+          signature = token_signature(
+            token.kind, token.text, token.leading, token.trailing, token.flags, token.expected_kind
+          )
+          bucket = @tokens[signature]
+          existing = find_token(
+            bucket, token.kind, token.text, token.leading, token.trailing, token.flags, token.expected_kind
+          )
+          return existing if existing
+
+          (@tokens[signature] ||= []) << token
+          token
+        end
+
+        # Intern a token before constructing it, avoiding discarded duplicate immutable values.
+        # @rbs (kind: Integer, text: String, ?leading: Array[GreenTrivia], ?trailing: Array[GreenTrivia],
+        #   ?flags: Integer, ?expected_kind: Integer?) -> GreenToken
+        def intern_token_fields(
+          kind:, text:, leading: EMPTY_TRIVIA, trailing: EMPTY_TRIVIA, flags: 0, expected_kind: nil
+        )
+          unless @enabled && flags.nobits?(Flags::HAS_ANNOTATION)
+            return GreenToken.new(
+              kind: kind, text: text, leading: leading, trailing: trailing,
+              flags: flags, expected_kind: expected_kind
+            )
+          end
+
+          comparable_text = if text.encoding == Encoding::BINARY || text.ascii_only?
+                              text
+                            else
+                              text.b.freeze
+                            end
+          signature = token_signature(kind, comparable_text, leading, trailing, flags, expected_kind)
+          bucket = @tokens[signature]
+          existing = find_token(bucket, kind, comparable_text, leading, trailing, flags, expected_kind)
+          return existing if existing
+
+          token = GreenToken.new(
+            kind: kind, text: comparable_text, leading: leading, trailing: trailing,
+            flags: flags, expected_kind: expected_kind
+          )
+          (@tokens[signature] ||= []) << token
+          token
+        end
+
+        # @rbs (GreenNode node) -> GreenNode
+        def intern_node(node)
+          return node unless @enabled
+          return node if node.children.length > @node_arity_limit
+          return node if node.descendant_count > @node_descendant_limit
+          return node unless node.flags.nobits?(Flags::HAS_ANNOTATION)
+
+          @nodes[node] ||= node
+        end
+
+        # @rbs () -> void
+        def clear
+          @trivia.clear
+          @tokens.clear
+          @nodes.clear
+        end
+
+        private
+
+        # @rbs (Integer kind, String text, Array[GreenTrivia] leading, Array[GreenTrivia] trailing,
+        #   Integer flags, Integer? expected_kind) -> Integer
+        def token_signature(kind, text, leading, trailing, flags, expected_kind)
+          kind.hash ^ text.hash ^ leading.hash ^ trailing.hash ^ flags.hash ^ expected_kind.hash
+        end
+
+        # @rbs (Array[GreenToken]? bucket, Integer kind, String text, Array[GreenTrivia] leading,
+        #   Array[GreenTrivia] trailing, Integer flags, Integer? expected_kind) -> GreenToken?
+        def find_token(bucket, kind, text, leading, trailing, flags, expected_kind)
+          return unless bucket
+
+          bucket.find do |token|
+            token.kind == kind &&
+              token.text == text &&
+              token.leading == leading &&
+              token.trailing == trailing &&
+              token.flags == flags &&
+              token.expected_kind == expected_kind
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ibex/runtime/cst/green/node.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "token" unless defined?(Ibex::Runtime::CST::GreenToken)
+
+module Ibex
+  module Runtime
+    module CST
+      # Immutable position-independent syntax node.
+      class GreenNode
+        # @rbs! type child = GreenNode | GreenToken
+
+        attr_reader :kind #: Integer
+        attr_reader :children #: Array[child]
+        attr_reader :flags #: Integer
+        attr_reader :intrinsic_flags #: Integer
+        attr_reader :annotations #: Array[SyntaxAnnotation]
+        attr_reader :full_width #: Integer
+        attr_reader :leading_width #: Integer
+        attr_reader :trailing_width #: Integer
+        attr_reader :descendant_count #: Integer
+
+        # @rbs (kind: Integer, children: Array[child], ?flags: Integer, ?annotations: Array[SyntaxAnnotation]) -> void
+        def initialize(kind:, children:, flags: 0, annotations: [])
+          @kind = kind
+          @children = children.dup.freeze
+          @annotations = annotations.dup.freeze
+          @intrinsic_flags = flags
+          @intrinsic_flags |= Flags::HAS_ANNOTATION unless @annotations.empty?
+          @flags = @children.reduce(@intrinsic_flags) { |value, child| value | child.flags }
+          @full_width = @children.sum(&:full_width)
+          @leading_width = edge_width(@children, :leading_width)
+          @trailing_width = edge_width(@children.reverse_each, :trailing_width)
+          @descendant_count = 1 + @children.sum(&:descendant_count)
+          freeze
+        end
+
+        # @rbs () -> String
+        def to_source
+          source = String.new(encoding: Encoding::BINARY)
+          pending = @children.reverse
+          until pending.empty?
+            child = pending.pop || raise("green source traversal underflow")
+            if child.is_a?(GreenNode)
+              child.children.reverse_each { |nested| pending << nested }
+              next
+            end
+
+            child.leading.each { |trivia| source << trivia.text }
+            source << child.text
+            child.trailing.each { |trivia| source << trivia.text }
+          end
+          source
+        end
+
+        # @rbs (untyped other) -> bool
+        def ==(other)
+          other.is_a?(GreenNode) && @kind == other.kind && @intrinsic_flags == other.intrinsic_flags &&
+            @annotations == other.annotations && @children == other.children
+        end
+        alias eql? ==
+
+        # @rbs () -> Integer
+        def hash = [@kind, @children, @intrinsic_flags, @annotations].hash
+
+        private
+
+        # @rbs (Enumerable[child] children, Symbol reader) -> Integer
+        def edge_width(children, reader)
+          child = children.find { |candidate| candidate.full_width.positive? }
+          return 0 unless child
+
+          reader == :leading_width ? child.leading_width : child.trailing_width
+        end
+      end
+    end
+  end
+end

data/lib/ibex/runtime/cst/green/token.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "../kind" unless defined?(Ibex::Runtime::CST::Flags)
+require_relative "trivia" unless defined?(Ibex::Runtime::CST::GreenTrivia)
+
+module Ibex
+  module Runtime
+    module CST
+      # Immutable position-independent terminal occurrence.
+      class GreenToken
+        empty_trivia = [] # @type var empty_trivia: Array[GreenTrivia]
+        EMPTY_TRIVIA = empty_trivia.freeze #: Array[GreenTrivia]
+
+        attr_reader :kind #: Integer
+        attr_reader :text #: String
+        attr_reader :leading #: Array[GreenTrivia]
+        attr_reader :trailing #: Array[GreenTrivia]
+        attr_reader :flags #: Integer
+        attr_reader :full_width #: Integer
+        attr_reader :leading_width #: Integer
+        attr_reader :trailing_width #: Integer
+        attr_reader :expected_kind #: Integer?
+        attr_reader :hash #: Integer
+
+        # @rbs (kind: Integer, text: String, ?leading: Array[GreenTrivia], ?trailing: Array[GreenTrivia],
+        #   ?flags: Integer, ?expected_kind: Integer?) -> void
+        def initialize(
+          kind:, text:, leading: EMPTY_TRIVIA, trailing: EMPTY_TRIVIA, flags: 0, expected_kind: nil
+        )
+          @kind = kind
+          @text = text.encoding == Encoding::BINARY && text.frozen? ? text : text.b.freeze
+          @leading = leading.frozen? ? leading : leading.dup.freeze
+          @trailing = trailing.frozen? ? trailing : trailing.dup.freeze
+          @flags = flags
+          @expected_kind = expected_kind
+          @leading_width = trivia_width(@leading)
+          @trailing_width = trivia_width(@trailing)
+          @full_width = @leading_width + @text.bytesize + @trailing_width
+          @hash = @kind.hash ^ @text.hash ^ @leading.hash ^ @trailing.hash ^ @flags.hash ^ @expected_kind.hash
+          freeze
+        end
+
+        # @rbs (kind: Integer, expected_kind: Integer) -> GreenToken
+        def self.missing(kind:, expected_kind:)
+          new(
+            kind: kind, text: "", expected_kind: expected_kind,
+            flags: Flags::CONTAINS_MISSING | Flags::SYNTHETIC
+          )
+        end
+
+        # @rbs (kind: Integer, text: String, ?leading: Array[GreenTrivia]) -> GreenToken
+        def self.lexical_error(kind:, text:, leading: [])
+          new(kind: kind, text: text, leading: leading, flags: Flags::CONTAINS_ERROR)
+        end
+
+        # @rbs () -> Integer
+        def descendant_count = 1
+
+        # @rbs () -> String
+        def to_source
+          source = String.new(encoding: Encoding::BINARY)
+          @leading.each { |trivia| source << trivia.text }
+          source << @text
+          @trailing.each { |trivia| source << trivia.text }
+          source
+        end
+
+        # @rbs (untyped other) -> bool
+        def ==(other)
+          other.is_a?(GreenToken) &&
+            @kind == other.kind &&
+            @text == other.text &&
+            @leading == other.leading &&
+            @trailing == other.trailing &&
+            @flags == other.flags &&
+            @expected_kind == other.expected_kind
+        end
+        alias eql? ==
+
+        # @rbs () -> Integer
+        private
+
+        # @rbs (Array[GreenTrivia] trivia) -> Integer
+        def trivia_width(trivia)
+          trivia.sum(&:full_width)
+        end
+      end
+    end
+  end
+end

data/lib/ibex/runtime/cst/green/trivia.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  module Runtime
+    module CST
+      # Immutable source text ignored by the grammar but owned by a token.
+      class GreenTrivia
+        attr_reader :kind #: Integer
+        attr_reader :text #: String
+        attr_reader :full_width #: Integer
+        attr_reader :hash #: Integer
+
+        # @rbs (kind: Integer, text: String) -> void
+        def initialize(kind:, text:)
+          @kind = kind
+          @text = text.b.freeze
+          @full_width = @text.bytesize
+          @hash = [@kind, @text].hash
+          freeze
+        end
+
+        # @rbs () -> String
+        def to_source = @text
+
+        # @rbs (untyped other) -> bool
+        def ==(other)
+          other.is_a?(GreenTrivia) && @kind == other.kind && @text == other.text
+        end
+        alias eql? ==
+
+        # @rbs () -> Integer
+      end
+    end
+  end
+end