idlc 0.1.2 → 0.1.5

data/lib/idlc/ast.rb

@@ -65,11 +65,15 @@ module Idl
 
     # @return [String] Source input file
     sig { returns(T.nilable(Pathname)) }
-    attr_reader :input_file
+    def input_file
+      @input_file || @parent&.input_file
+    end
 
     # @return [Integer] Starting line in the source input file (i.e., position 0 of {#input} in the file)
     sig { returns(Integer) }
-    attr_reader :starting_line
+    def starting_line
+      @starting_line || @parent&.starting_line || 0
+    end
 
     # @return [String] Source string
     sig { returns(T.nilable(String)) }
@@ -212,6 +216,14 @@ module Idl
     sig { abstract.params(symtab: SymbolTable).returns(T::Boolean) }
     def const_eval?(symtab); end
 
+    # @return [Boolean] whether this node includes the Executable interface
+    sig { overridable.returns(T::Boolean).checked(:never) }
+    def executable? = false
+
+    # @return [Boolean] whether this node includes the Declaration interface
+    sig { overridable.returns(T::Boolean).checked(:never) }
+    def declaration? = false
+
     # @param input [String] The source being compiled
     # @param interval [Range] The range in the source corresponding to this AstNode
     # @param children [Array<AstNode>] Children of this node
@@ -247,7 +259,7 @@ module Idl
     # @param [Integer] starting_line The starting line number in the input file.
     # @param [Integer] starting_offset The byte offset in the file where the IDL content starts.
     # @param [Array<Integer>, nil] line_file_offsets Per-IDL-line file byte offsets (nil = use starting_offset).
-    sig { params(filename: T.any(Pathname, String), starting_line: Integer, starting_offset: Integer, line_file_offsets: T.nilable(T::Array[Integer])).void }
+    sig { params(filename: T.any(Pathname, String), starting_line: Integer, starting_offset: Integer, line_file_offsets: T.nilable(T::Array[Integer])).void.checked(:never) }
     def set_input_file_unless_already_set(filename, starting_line = 0, starting_offset = 0, line_file_offsets = nil)
       return unless @input_file.nil?
 
@@ -255,10 +267,6 @@ module Idl
       @starting_line = starting_line
       @starting_offset = starting_offset
       @line_file_offsets = line_file_offsets
-      children.each do |child|
-        child.set_input_file_unless_already_set(filename, starting_line, starting_offset, line_file_offsets)
-      end
-      raise "?" if @starting_line.nil?
     end
 
     # remember where the code comes from
@@ -267,22 +275,18 @@ module Idl
     # @param starting_line [Integer] Starting line in the file
     # @param starting_offset [Integer] Byte offset in the file where the IDL content starts
     # @param line_file_offsets [Array<Integer>, nil] Per-IDL-line file byte offsets (nil = use starting_offset).
-    sig { params(filename: T.any(Pathname, String), starting_line: Integer, starting_offset: Integer, line_file_offsets: T.nilable(T::Array[Integer])).void }
+    sig { params(filename: T.any(Pathname, String), starting_line: Integer, starting_offset: Integer, line_file_offsets: T.nilable(T::Array[Integer])).void.checked(:never) }
     def set_input_file(filename, starting_line = 0, starting_offset = 0, line_file_offsets = nil)
       @input_file = Pathname.new(filename)
       @starting_line = starting_line
       @starting_offset = starting_offset
       @line_file_offsets = line_file_offsets
-      children.each do |child|
-        child.set_input_file(filename, starting_line, starting_offset, line_file_offsets)
-      end
-      raise "?" if @starting_line.nil?
     end
 
     # @return [Integer] the current line number
     sig { returns(Integer) }
     def lineno
-      T.must(T.must(input)[0..T.must(interval).first]).count("\n") + 1 + (@starting_line.nil? ? 0 : @starting_line)
+      T.must(T.must(input)[0..T.must(interval).first]).count("\n") + 1 + starting_line
     end
 
     # @return [AstNode] the first ancestor that is_a?(+klass+)
@@ -378,7 +382,7 @@ module Idl
       starting_lineno = T.must(T.must(input)[0..lines_interval.min]).count("\n")
       lines = lines.lines.map do |line|
         starting_lineno += 1
-        "#{@starting_line + starting_lineno - 1}: #{line}"
+        "#{starting_line + starting_lineno - 1}: #{line}"
       end.join("")
 
       msg = <<~WHAT
@@ -415,6 +419,57 @@ module Idl
       attr_accessor :value_error_reason, :value_error_ast
     end
 
+    # Extract the base variable name from a potentially nested access chain
+    # @param node [RvalueAst] The node to extract from
+    # @return [String, nil] The base variable name, or nil if not extractable
+    sig { params(node: RvalueAst).returns(T.nilable(String)) }
+    def self.extract_base_var_name(node)
+      case node
+      when IdAst
+        node.name
+      when AryElementAccessAst, AryRangeAccessAst
+        extract_base_var_name(node.var)
+      else
+        nil
+      end
+    end
+
+    # Perform write-back for nested array access assignments
+    # Handles arbitrary nesting depth: v[a][b][c] = val recursively writes back through the chain
+    # @param target [RvalueAst] The target expression (possibly nested)
+    # @param new_value [Integer] The new value to write
+    # @param symtab [SymbolTable] The symbol table
+    # @return [void]
+    sig { params(target: RvalueAst, new_value: ValueRbType, symtab: SymbolTable).void }
+    def self.write_back_nested(target, new_value, symtab)
+      case target
+      when IdAst
+        # Base case: simple variable
+        existing_var = symtab.get(target.name)
+        raise InternalError, "write_back_nested: '#{target.name}' not found in symbol table" if existing_var.nil?
+        existing_var.value = new_value
+      when AryElementAccessAst
+        # Recursive case: v[idx] = val
+        # Read parent, modify element, write back parent
+        parent_value = target.var.value(symtab)
+        idx_val = target.index.value(symtab)
+        parent_value[idx_val] = new_value
+        # Recursively write back the parent (which may itself be nested)
+        write_back_nested(target.var, parent_value, symtab)
+      when AryRangeAccessAst
+        # Recursive case: v[msb:lsb] = new_value
+        # Read parent, splice new_value into [msb:lsb], write parent back
+        parent_value = T.cast(target.var.value(symtab), Integer)
+        msb_val = T.cast(target.msb.value(symtab), Integer)
+        lsb_val = T.cast(target.lsb.value(symtab), Integer)
+        mask = ((1 << (msb_val - lsb_val + 1)) - 1) << lsb_val
+        updated_parent = (parent_value & ~mask) | ((T.cast(new_value, Integer) << lsb_val) & mask)
+        write_back_nested(target.var, updated_parent, symtab)
+      else
+        raise InternalError, "Unknown target type for write-back: #{target.class.name}"
+      end
+    end
+
     # raise a value error, indicating that the value is not known at compile time
     #
     # @param reason [String] Error message
@@ -512,11 +567,11 @@ module Idl
     #  end: <0-indexed position of the ending character in the input>
     sig { returns(T::Hash[String, T.untyped]) }
     def source_yaml
-      base_offset = @starting_offset || 0
+      base_offset = source_starting_offset
       interval_begin = T.must(interval).begin
       interval_end = T.must(interval).size == 0 ? T.must(interval).begin + 1 : T.must(interval).end
 
-      lfo = @line_file_offsets
+      lfo = source_line_file_offsets
       if lfo
         # Map an IDL-string position to a file byte offset using the per-line table.
         # Each entry lfo[i] is the file offset of the first character of IDL line i.
@@ -539,12 +594,23 @@ module Idl
       end
 
       {
-        "file" => @input_file.to_s,
+        "file" => T.must(input_file).to_s,
         "begin" => file_begin,
         "end"   => file_end
       }
     end
 
+    sig { returns(Integer) }
+    def source_starting_offset
+      @starting_offset || @parent&.source_starting_offset || 0
+    end
+
+    sig { returns(T.nilable(T::Array[Integer])) }
+    def source_line_file_offsets
+      return @line_file_offsets unless @line_file_offsets.nil?
+      @parent&.source_line_file_offsets
+    end
+
     private
 
     # Given an IDL-string position +pos+ and the per-line file-offset table +lfo+,
@@ -673,7 +739,10 @@ module Idl
   module Executable
     extend T::Sig
     extend T::Helpers
-    interface!
+    abstract!
+
+    sig { returns(T::Boolean).checked(:never) }
+    def executable? = true
 
     # @!macro [new] execute
     #   "execute" the statement by updating the variables in the symbol table
@@ -860,7 +929,10 @@ module Idl
   module Declaration
     extend T::Sig
     extend T::Helpers
-    interface!
+    abstract!
+
+    sig { returns(T::Boolean).checked(:never) }
+    def declaration? = true
 
     # @!macro [new] add_symbol
     #  Add symbol(s) at the outermost scope of the symbol table
@@ -1339,9 +1411,13 @@ module Idl
 
       enums.each { |g| g.add_symbol(symtab); }
       bitfields.each { |g| g.add_symbol(symtab) }
+      # Functions must be registered before globals so that global variable
+      # initializers can call functions (e.g. FLEN = implemented?(...) ? 64 : 32).
+      # FunctionDefAst#add_symbol only stores the FunctionType; it does not
+      # evaluate the body, so adding functions before globals is safe.
+      functions.each { |g| g.add_symbol(symtab) }
       globals.each { |g| g.add_symbol(symtab) }
       structs.each { |g| g.add_symbol(symtab) }
-      functions.each { |g| g.add_symbol(symtab) }
     end
 
     # replaces an include statement with the ast in that file, making
@@ -1418,7 +1494,9 @@ module Idl
         end
       end
 
-      IsaAst.new(input, interval, kids)
+      node = IsaAst.new(input, interval, kids)
+      node.set_input_file(yaml.fetch("source").fetch("file"))
+      node
     end
   end
 
@@ -1493,12 +1571,6 @@ module Idl
     end
   end
 
-  class ArraySizeSyntaxNode < SyntaxNode
-    def to_ast
-      ArraySizeAst.new(input, interval, send(:expression).to_ast)
-    end
-  end
-
   class ArraySizeAst < AstNode
     include Rvalue
 
@@ -1560,25 +1632,21 @@ module Idl
   end
 
 
-  class EnumSizeSyntaxNode < SyntaxNode
-    def to_ast
-      EnumSizeAst.new(input, interval, send(:type_name).to_ast)
-    end
-  end
-
   # represents the builtin that returns the nymber of elements in an enum class
   #
   #  $enum_size(XRegWidth) #=> 2
   class EnumSizeAst < AstNode
     include Rvalue
 
-    def enum_class = children[0]
+    def enum_class = children.fetch(0)
 
     sig { override.params(symtab: SymbolTable).returns(T::Boolean) }
     def const_eval?(symtab) = true
 
+    sig { params(input: T.nilable(String), interval: T.nilable(T::Range[Integer]), enum_class_name: T.any(IdAst, UserTypeNameAst)).void }
     def initialize(input, interval, enum_class_name)
-      super(input, interval, [enum_class_name])
+      user_type_name = enum_class_name.is_a?(UserTypeNameAst) ? enum_class_name : UserTypeNameAst.new(enum_class_name.input, enum_class_name.interval, enum_class_name.name)
+      super(input, interval, [user_type_name])
     end
 
     def type_check(symtab, strict:)
@@ -1615,17 +1683,11 @@ module Idl
       interval = interval_from_source_yaml(yaml.fetch("source"))
       EnumSizeAst.new(
         input, interval,
-        T.cast(AstNode.from_h(yaml.fetch("enum_class_name"), source_mapper), T.all(Rvalue, AstNode))
+        T.cast(AstNode.from_h(yaml.fetch("enum_class_name"), source_mapper), UserTypeNameAst)
       )
     end
   end
 
-  class EnumElementSizeSyntaxNode < SyntaxNode
-    def to_ast
-      EnumElementSizeAst.new(input, interval, send(:type_name).to_ast)
-    end
-  end
-
   # represents the builtin that returns the bitwidth of an element in an enum class
   #
   #  $enum_element_size(PrivilegeMode) #=> 3
@@ -1637,9 +1699,10 @@ module Idl
     sig { override.params(symtab: SymbolTable).returns(T::Boolean) }
     def const_eval?(symtab) = true
 
-    sig { params(input: T.nilable(String), interval: T.nilable(T::Range[Integer]), enum_class_name: UserTypeNameAst).void }
+    sig { params(input: T.nilable(String), interval: T.nilable(T::Range[Integer]), enum_class_name: T.any(IdAst, UserTypeNameAst)).void }
     def initialize(input, interval, enum_class_name)
-      super(input, interval, [enum_class_name])
+      user_type_name = enum_class_name.is_a?(UserTypeNameAst) ? enum_class_name : UserTypeNameAst.new(enum_class_name.input, enum_class_name.interval, enum_class_name.name)
+      super(input, interval, [user_type_name])
     end
 
     def type_check(symtab, strict:)
@@ -1677,12 +1740,6 @@ module Idl
     end
   end
 
-  class EnumCastSyntaxNode < SyntaxNode
-    def to_ast
-      EnumCastAst.new(input, interval, send(:type_name).to_ast, send(:expression).to_ast)
-    end
-  end
-
   class EnumCastAst < AstNode
     include Rvalue
 
@@ -1690,22 +1747,23 @@ module Idl
     def const_eval?(symtab) = true
 
     # @return [UserTypeAst] Enum name
-    def enum_name = @children[0]
+    def enum_name = @children.fetch(0)
 
     # @return [Rvalue] Value expression
-    def expression = @children[1]
+    def expression = @children.fetch(1)
 
     sig {
       params(
         input: T.nilable(String),
         interval: T.nilable(T::Range[Integer]),
-        type_name: UserTypeNameAst,
+        type_name: T.any(IdAst, UserTypeNameAst),
         expression: RvalueAst
       )
       .void
     }
     def initialize(input, interval, type_name, expression)
-      super(input, interval, [type_name, expression])
+      user_type_name = type_name.is_a?(UserTypeNameAst) ? type_name : UserTypeNameAst.new(type_name.input, type_name.interval, type_name.name)
+      super(input, interval, [user_type_name, expression])
     end
 
     def type_check(symtab, strict:)
@@ -1758,26 +1816,21 @@ module Idl
     end
   end
 
-  class EnumArrayCastSyntaxNode < SyntaxNode
-    def to_ast
-      EnumArrayCastAst.new(input, interval, send(:type_name).to_ast)
-    end
-  end
-
   # represents the builtin that returns an array with all elements of an Enum type
   #
   #  $enum_to_a(PrivilegeMode) #=> [3, 1, 1, 0, 5, 4]
   class EnumArrayCastAst < AstNode
     include Rvalue
 
-    def enum_class = children[0]
+    def enum_class = children.fetch(0)
 
     sig { override.params(symtab: SymbolTable).returns(T::Boolean) }
     def const_eval?(symtab) = true
 
-    sig { params(input: T.nilable(String), interval: T.nilable(T::Range[Integer]), enum_class_name: UserTypeNameAst).void }
+    sig { params(input: T.nilable(String), interval: T.nilable(T::Range[Integer]), enum_class_name: T.any(IdAst, UserTypeNameAst)).void }
     def initialize(input, interval, enum_class_name)
-      super(input, interval, [enum_class_name])
+      user_type_name = enum_class_name.is_a?(UserTypeNameAst) ? enum_class_name : UserTypeNameAst.new(enum_class_name.input, enum_class_name.interval, enum_class_name.name)
+      super(input, interval, [user_type_name])
     end
 
     def type_check(symtab, strict:)
@@ -2479,7 +2532,12 @@ module Idl
 
     sig { override.params(symtab: SymbolTable).returns(T::Boolean) }
     def const_eval?(symtab)
-      if var.name == "X"
+      var_type = begin
+        var.type(symtab)
+      rescue AstNode::TypeError, AstNode::InternalError
+        nil
+      end
+      if var_type.is_a?(Type) && var_type.kind == :array && var_type.sub_type.is_a?(RegFileElementType) && var_type.qualifiers.include?(:global)
         false
       else
         var.const_eval?(symtab) && index.const_eval?(symtab)
@@ -2544,7 +2602,12 @@ module Idl
       if var.type(symtab).integral?
         (var_val >> index.value(symtab)) & 1
       else
-        value_error "X registers are not compile-time-known" if var.text_value == "X"
+        var_type = begin
+          var.type(symtab)
+        rescue AstNode::TypeError, AstNode::InternalError
+          nil
+        end
+        value_error "Register file registers are not compile-time-known" if var_type.is_a?(Type) && var_type.kind == :array && var_type.sub_type.is_a?(RegFileElementType) && var_type.qualifiers.include?(:global)
 
         # internal_error "Not an array" unless ary.type.kind == :array
 
@@ -2589,7 +2652,12 @@ module Idl
     sig { override.params(symtab: SymbolTable).returns(T::Boolean) }
     def const_eval?(symtab)
       v = var
-      if v.is_a?(IdAst) && v.name == "X"
+      var_type = begin
+        v.type(symtab)
+      rescue AstNode::TypeError, AstNode::InternalError
+        nil
+      end
+      if var_type.is_a?(Type) && var_type.kind == :array && var_type.sub_type.is_a?(RegFileElementType) && var_type.qualifiers.include?(:global)
         false
       else
         v.const_eval?(symtab) && msb.const_eval?(symtab).const_eval? && lsb.const_eval?(symtab)
@@ -2853,12 +2921,6 @@ module Idl
     end
   end
 
-  class AryElementAssignmentSyntaxNode < SyntaxNode
-    def to_ast
-      AryElementAssignmentAst.new(input, interval, send(:var).to_ast, send(:idx).to_ast, send(:rval).to_ast)
-    end
-  end
-
   # represents an array element assignment
   #
   # for example:
@@ -2873,8 +2935,10 @@ module Idl
       if idx.const_eval?(symtab) && rhs.const_eval?(symtab)
         true
       else
-        lhs_var = symtab.get(lhs.name)
-        type_error "array #{lhs.name} has not been declared" if lhs_var.nil?
+        base_name = AstNode.extract_base_var_name(lhs)
+        type_error "Cannot determine base variable for #{lhs.text_value}" if base_name.nil?
+        lhs_var = symtab.get(base_name)
+        type_error "array #{base_name} has not been declared" if lhs_var.nil?
 
         lhs_var.const_incompatible!
         false
@@ -2940,13 +3004,15 @@ module Idl
           value_error "right-hand side of array element assignment is unknown"
         end
       when :bits
-        var = symtab.get(lhs.text_value)
         value_result = value_try do
-          v = rhs.value(symtab)
-          var.value = (lhs.value(symtab) & ~0) | ((v & 1) << idx.value(symtab))
+          new_element = (lhs.value(symtab) & ~0) | ((rhs.value(symtab) & 1) << idx.value(symtab))
+          AstNode.write_back_nested(lhs, new_element, symtab)
         end
         value_else(value_result) do
-          var.value = nil
+          base_name = T.must(AstNode.extract_base_var_name(lhs))
+          v = symtab.get(base_name)
+          internal_error "did not find array base '#{base_name}'" if v.nil?
+          v.value = nil
         end
       else
         internal_error "unexpected type for array element assignment"
@@ -2983,7 +3049,27 @@ module Idl
 
   class AryRangeAssignmentSyntaxNode < SyntaxNode
     def to_ast
-      AryRangeAssignmentAst.new(input, interval, send(:var).to_ast, send(:msb).to_ast, send(:lsb).to_ast, send(:rval).to_ast)
+      var = send(:var).to_ast
+      brackets = send(:brackets).elements
+
+      # Build access chain for all but the last bracket
+      brackets[0..-2].each do |bracket|
+        var =
+          if bracket.msb.empty?
+            AryElementAccessAst.new(input, interval, var, bracket.lsb.to_ast)
+          else
+            AryRangeAccessAst.new(input, interval, var,
+                                  bracket.msb.expression.to_ast, bracket.lsb.to_ast)
+          end
+      end
+
+      # Use accumulated `var` for the assignment target
+      last_bracket = brackets[-1]
+      if last_bracket.msb.empty?
+        AryElementAssignmentAst.new(input, interval, var, last_bracket.lsb.to_ast, send(:rval).to_ast)
+      else
+        AryRangeAssignmentAst.new(input, interval, var, last_bracket.msb.expression.to_ast, last_bracket.lsb.to_ast, send(:rval).to_ast)
+      end
     end
   end
 
@@ -3001,8 +3087,10 @@ module Idl
       if lsb.const_eval?(symtab) && msb.const_eval?(symtab) && write_value.const_eval?(symtab)
         true
       else
-        lhs_var = symtab.get(variable.name)
-        type_error "array #{variable.name} has not be declared" if lhs_var.nil?
+        base_name = AstNode.extract_base_var_name(variable)
+        type_error "Cannot determine base variable for #{variable.text_value}" if base_name.nil?
+        lhs_var = symtab.get(base_name)
+        type_error "array #{base_name} has not be declared" if lhs_var.nil?
 
         lhs_var.const_incompatible!
         false
@@ -3060,26 +3148,29 @@ module Idl
     def execute(symtab)
       return if variable.type(symtab).global?
 
-      var = symtab.get(variable.name)
-      internal_error "Variable #{variable.name} not found" if var.nil?
-
       value_result = value_try do
-        var_val = variable.value(symtab)
-
         msb_val = msb.value(symtab)
         lsb_val = lsb.value(symtab)
 
         type_error "MSB (#{msb_val}) is <= LSB (#{lsb_val})" if msb_val <= lsb_val
 
         rval_val = write_value.value(symtab)
-
         mask = ((1 << (msb_val - lsb_val + 1)) - 1) << lsb_val
 
-        var.value = (var_val & ~mask) | ((rval_val << lsb_val) & mask)
+        # Read current value, modify bits
+        var_val = variable.value(symtab)
+        var_val &= ~mask
+        new_val = var_val | ((rval_val << lsb_val) & mask)
+
+        # Write back through the access chain
+        AstNode.write_back_nested(variable, new_val, symtab)
         :ok
       end
       value_else(value_result) do
-        var.value = nil
+        base_name = T.must(AstNode.extract_base_var_name(variable))
+        v = symtab.get(base_name)
+        internal_error "did not find array base" if v.nil?
+        v.value = nil
         value_error "Either the range or right-hand side of an array range assignment is unknown"
       end
     end
@@ -3217,7 +3308,13 @@ module Idl
         var.value = bitfield_val
       elsif var.type.kind == :struct
         struct_val = id.value(symtab)
-        struct_val[@field_name] = rhs.value(symtab)
+        value_result = value_try do
+          struct_val[@field_name] = rhs.value(symtab)
+        end
+        value_else(value_result) do
+          struct_val[@field_name] = nil
+          value_error ""
+        end
       else
         value_error "TODO: Field assignment execution"
       end
@@ -5273,6 +5370,10 @@ module Idl
     # @!macro value
     def value(symtab) = expression.value(symtab)
 
+    def max_value(symtab) = expression.max_value(symtab)
+
+    def min_value(symtab) = expression.min_value(symtab)
+
     # @!macro to_idl
     sig { override.returns(String) }
     def to_idl = "(#{expression.to_idl})"
@@ -5702,6 +5803,120 @@ module Idl
     end
   end
 
+  # Generic syntax node for $name(arg, ...) — dispatches to the correct typed AstNode in to_ast.
+  class DollarFunctionCallSyntaxNode < SyntaxNode
+    def to_ast
+      dollar_name = "$#{send(:name).text_value}"
+      arg_nodes = dollar_arg_list_elements
+      enum_type_name_validation = {
+        0 => {
+          classes: [IdAst, UserTypeNameAst],
+          description: "an identifier or user type name"
+        }
+      }
+
+      case dollar_name
+      when "$width"             then builtin_call_ast(dollar_name, arg_nodes, 1, WidthRevealAst)
+      when "$signed"            then builtin_call_ast(dollar_name, arg_nodes, 1, SignCastAst)
+      when "$bits"              then builtin_call_ast(dollar_name, arg_nodes, 1, BitsCastAst)
+      when "$enum_size"         then builtin_call_ast(dollar_name, arg_nodes, 1, EnumSizeAst, enum_type_name_validation)
+      when "$enum_element_size" then builtin_call_ast(dollar_name, arg_nodes, 1, EnumElementSizeAst, enum_type_name_validation)
+      when "$enum_to_a"         then builtin_call_ast(dollar_name, arg_nodes, 1, EnumArrayCastAst, enum_type_name_validation)
+      when "$enum"              then builtin_call_ast(dollar_name, arg_nodes, 2, EnumCastAst, enum_type_name_validation)
+      when "$array_size"        then builtin_call_ast(dollar_name, arg_nodes, 1, ArraySizeAst)
+      when "$array_includes?"   then builtin_call_ast(dollar_name, arg_nodes, 2, ArrayIncludesAst)
+      else
+        ParseTimeDetectedTypeError.new(input, interval, "#{dollar_name} is not a builtin function")
+      end
+    end
+
+    private
+
+    def builtin_call_ast(dollar_name, arg_nodes, expected_arg_count, ast_class, arg_type_validations = {})
+      if arg_nodes.size != expected_arg_count
+        ParseTimeDetectedTypeError.new(input, interval, "#{dollar_name} expects #{expected_arg_count} argument#{expected_arg_count == 1 ? "" : "s"}; #{arg_nodes.size} given")
+      else
+        arg_asts = arg_nodes.first(expected_arg_count).map(&:to_ast)
+
+        arg_type_validations.each do |arg_index, validation|
+          next if validation[:classes].any? { |klass| arg_asts[arg_index].is_a?(klass) }
+
+          return ParseTimeDetectedTypeError.new(
+            input,
+            interval,
+            "#{dollar_name} expects argument #{arg_index + 1} to be #{validation[:description]}; #{builtin_arg_type_name(arg_asts[arg_index])} given"
+          )
+        end
+
+        ast_class.new(input, interval, *arg_asts)
+      end
+    end
+
+    def builtin_arg_type_name(arg_ast)
+      arg_ast.class.name.split("::").last
+    end
+
+    private
+
+    def dollar_arg_list_elements
+      arg_list = send(:args)
+      first = arg_list.first
+      rest = arg_list.rest.elements.map { |e| e.expression }
+      first.empty? ? rest : [first] + rest
+    end
+
+  end
+
+  # Generic syntax node for $name (no parens) — creates a BuiltinVariableAst.
+  class DollarVariableSyntaxNode < SyntaxNode
+    def to_ast
+      BuiltinVariableAst.new(input, interval, "$#{send(:name).text_value}")
+    end
+  end
+
+  # Syntax node for $name = expr — dispatches to PcAssignmentAst for $pc,
+  class DollarVariableAssignmentSyntaxNode < SyntaxNode
+    def to_ast
+      dollar_name = "$#{send(:dollar_variable).send(:name).text_value}"
+      rhs = send(:rval).to_ast
+      case dollar_name
+      when "$pc"
+        PcAssignmentAst.new(input, interval, rhs)
+      else
+        ParseTimeDetectedTypeError.new(input, interval, "#{dollar_name} is not assignable")
+      end
+    end
+  end
+
+  # AstNode for an error detected during to_ast. Always causes a type error
+  class ParseTimeDetectedTypeError < AstNode
+
+    sig { override.params(symtab: SymbolTable).returns(T::Boolean) }
+    def const_eval?(symtab) = true
+
+    def initialize(input, interval, reason)
+      super(input, interval, EMPTY_ARRAY)
+      @reason = reason
+    end
+
+    sig { override.params(symtab: SymbolTable, strict: T::Boolean).void }
+    def type_check(symtab, strict:)
+      type_error @reason
+    end
+
+    sig { params(symtab: SymbolTable).returns(Type) }
+    def type(symtab) = type_error(@reason)
+
+    sig { params(symtab: SymbolTable).returns(T.untyped) }
+    def value(symtab) = value_error "Can't take value of a type error"
+
+    sig { override.returns(String) }
+    def to_idl = text_value
+
+    sig { override.returns(T::Hash[String, T.untyped]) }
+    def to_h = { "kind" => "ParseTimeDetectedTypeError", "reason" => @reason, "source" => source_yaml }
+  end
+
   class PostIncrementExpressionSyntaxNode < SyntaxNode
     def to_ast
       PostIncrementExpressionAst.new(input, interval, send(:rval).to_ast)
@@ -5846,7 +6061,9 @@ module Idl
         range = T.cast(obj.type(symtab), BitfieldType).range(@field_name)
         (T.cast(obj.value(symtab), Integer) >> range.first) & ((1 << range.size) - 1)
       elsif kind(symtab) == :struct
-        T.cast(obj.value(symtab), T::Hash[String, BasicValueRbType])[@field_name]
+        field_val = T.cast(obj.value(symtab), T::Hash[String, BasicValueRbType])[@field_name]
+        value_error "#{@field_name} is not known at compile-time" if field_val.nil?
+        field_val
       else
         type_error "#{obj.text_value} is Not a bitfield."
       end
@@ -6261,6 +6478,34 @@ module Idl
       end
     end
 
+    # @!macro max_value
+    def max_value(symtab)
+      value_result = value_try do
+        cond = condition.value(symtab)
+        return cond ? true_expression.max_value(symtab) : false_expression.max_value(symtab)
+      end
+      value_else(value_result) do
+        t = true_expression.max_value(symtab)
+        f = false_expression.max_value(symtab)
+        return :unknown if t == :unknown || f == :unknown
+        [t, f].max
+      end
+    end
+
+    # @!macro min_value
+    def min_value(symtab)
+      value_result = value_try do
+        cond = condition.value(symtab)
+        return cond ? true_expression.min_value(symtab) : false_expression.min_value(symtab)
+      end
+      value_else(value_result) do
+        t = true_expression.min_value(symtab)
+        f = false_expression.min_value(symtab)
+        return :unknown if t == :unknown || f == :unknown
+        [t, f].min
+      end
+    end
+
     # @!macro to_idl
     sig { override.returns(String) }
     def to_idl = "#{condition.to_idl} ? #{true_expression.to_idl} : #{false_expression.to_idl}"
@@ -6352,10 +6597,10 @@ module Idl
 
     # @!macro execute
     def execute(symtab)
-      if action.is_a?(Declaration)
+      if action.declaration?
         action.add_symbol(symtab)
       end
-      if action.is_a?(Executable)
+      if action.executable?
         action.execute(symtab)
       end
     end
@@ -6408,7 +6653,7 @@ module Idl
     # @!macro type_check
     def type_check(symtab, strict:)
       action.type_check(symtab, strict:)
-      type_error "Cannot declare from a conditional statement" if action.is_a?(Declaration)
+      type_error "Cannot declare from a conditional statement" if action.declaration?
 
       condition.type_check(symtab, strict:)
       type_error "condition is not boolean" unless condition.type(symtab).convertable_to?(:boolean)
@@ -7884,7 +8129,7 @@ module Idl
       stmts.each do |s|
         if s.is_a?(Returns)
           return s.return_type(symtab)
-        elsif s.action.is_a?(Declaration)
+        elsif s.action.declaration?
           s.action.add_symbol(symtab)
         end
       end