mos6502-workbench 1.0.0

data/lib/mos6502/workbench/assembler.rb

@@ -0,0 +1,725 @@
+# frozen_string_literal: true
+
+module MOS6502
+  # Raised when assembly source cannot be parsed or encoded.
+  class AssemblyError < StandardError; end
+
+  # A minimal two-pass assembler for the subset of 6502 syntax needed by this project.
+  #
+  # Supported features:
+  # - labels with `label:`
+  # - directives: `.org`, `.byte`, `.word`
+  # - numeric expressions with labels, `+`, `-`, unary `<` and `>`
+  # - the implemented official NMOS 6502 opcodes and addressing modes
+  class Assembler
+    INTEL_HEX_EOF_RECORD = ":00000001FF\n"
+
+    # A contiguous block of machine code emitted at a specific address.
+    Segment = Struct.new(:start_address, :bytes)
+
+    # The assembled program, including labels and one or more emitted segments.
+    Program = Struct.new(:segments, :labels, :entry_point) do
+      # Returns the lowest emitted address.
+      #
+      # @return [Integer] the first address occupied by any segment
+      def start_address
+        segments.min_by(&:start_address)&.start_address || entry_point
+      end
+
+      # Returns the first address after the final emitted byte.
+      #
+      # @return [Integer] the exclusive end address of the emitted program
+      def end_address
+        segments.map { |segment| segment.start_address + segment.bytes.length }.max || entry_point
+      end
+
+      # Loads the program into a CPU instance.
+      #
+      # @param cpu [CPU] the destination CPU
+      # @param set_reset_vector [Boolean] whether to install the reset vector
+      # @param reset [Boolean] whether to reset the CPU after loading
+      # @return [CPU] the CPU instance
+      def load_into(cpu, set_reset_vector: true, reset: true)
+        segments.each do |segment|
+          cpu.load(segment.bytes, start_address: segment.start_address, set_reset_vector: false)
+        end
+
+        cpu.write_word(CPU::RESET_VECTOR, entry_point) if set_reset_vector
+        cpu.reset(program_counter: set_reset_vector ? nil : entry_point) if reset
+        cpu
+      end
+
+      # Converts the emitted segments into a flat binary blob.
+      #
+      # Gaps between segments are filled with `fill_byte`. By default the image
+      # begins at the lowest segment address and extends through the final byte
+      # of the last segment.
+      #
+      # @param origin [Integer, nil] the base address of the output image
+      # @param size [Integer, nil] the fixed output size in bytes
+      # @param fill_byte [Integer] the byte used to fill gaps
+      # @return [String] the flat binary image
+      def to_flat_binary(origin: nil, size: nil, fill_byte: 0x00)
+        base = origin || start_address
+        fill = fill_byte & 0xff
+        required_size = [end_address - base, 0].max
+        image_size = size || required_size
+
+        raise AssemblyError, 'Binary size must be non-negative' if image_size.negative?
+        raise AssemblyError, 'Output image does not fit all segments' if image_size < required_size
+
+        image = Array.new(image_size, fill)
+
+        segments.each do |segment|
+          offset = segment.start_address - base
+          if offset.negative?
+            raise AssemblyError,
+                  "Segment at $#{format('%04X', segment.start_address)} starts before origin $#{format('%04X', base)}"
+          end
+
+          segment.bytes.each_with_index do |byte, index|
+            image[offset + index] = byte
+          end
+        end
+
+        image.pack('C*')
+      end
+
+      # Writes the program as a flat binary file.
+      #
+      # @param path [String] the output file path
+      # @param origin [Integer, nil] the base address of the output image
+      # @param size [Integer, nil] the fixed output size in bytes
+      # @param fill_byte [Integer] the byte used to fill gaps
+      # @return [String] the output path
+      def write_flat_binary(path, origin: nil, size: nil, fill_byte: 0x00)
+        File.binwrite(path, to_flat_binary(origin:, size:, fill_byte:))
+        path
+      end
+
+      # Converts the emitted segments into Intel HEX text records.
+      #
+      # Each data record preserves the original segment address, so sparse
+      # layouts remain sparse instead of being padded into a single image.
+      #
+      # @param bytes_per_record [Integer] the maximum payload size for each data record
+      # @return [String] the Intel HEX document
+      def to_intel_hex(bytes_per_record: 16)
+        raise AssemblyError, 'Intel HEX bytes_per_record must be positive' unless bytes_per_record.is_a?(Integer) && bytes_per_record.positive?
+
+        records = segments.sort_by(&:start_address).flat_map do |segment|
+          segment.bytes.each_slice(bytes_per_record).with_index.map do |slice, index|
+            address = (segment.start_address + (index * bytes_per_record)) & 0xffff
+            intel_hex_record(address, 0x00, slice)
+          end
+        end
+
+        (records << Assembler::INTEL_HEX_EOF_RECORD).join
+      end
+
+      # Writes the program as an Intel HEX file.
+      #
+      # @param path [String] the output file path
+      # @param bytes_per_record [Integer] the maximum payload size for each data record
+      # @return [String] the output path
+      def write_intel_hex(path, bytes_per_record: 16)
+        File.write(path, to_intel_hex(bytes_per_record:))
+        path
+      end
+
+      private
+
+      # Builds a single Intel HEX record line with the correct checksum.
+      #
+      # @param address [Integer] the 16-bit record address
+      # @param record_type [Integer] the Intel HEX record type
+      # @param data [Array<Integer>] the payload bytes
+      # @return [String] the encoded record line
+      def intel_hex_record(address, record_type, data)
+        bytes = [data.length, (address >> 8) & 0xff, address & 0xff, record_type, *data]
+        checksum = ((-bytes.sum) & 0xff)
+        ":#{bytes.map { |byte| format('%02X', byte) }.join}#{format('%02X', checksum)}\n"
+      end
+    end
+
+    Statement = Struct.new(:line_number, :label, :kind, :name, :argument, :raw)
+
+    DEFAULT_ORIGIN = CPU::DEFAULT_LOAD_ADDRESS
+    BRANCH_MNEMONICS = %i[bcc bcs beq bmi bne bpl bvc bvs].freeze
+    DIRECTIVES = %w[.org .byte .word].freeze
+    MAX_PASSES = 8
+
+    OPCODES_BY_MNEMONIC = CPU::OPCODES.each_with_object(Hash.new { |hash, key| hash[key] = {} }) do |(opcode, (mnemonic, mode)), hash|
+      hash[mnemonic][mode] = opcode
+    end.freeze
+
+    # Assembles 6502 source code into a {Program}.
+    #
+    # @param source [String] the source code to assemble
+    # @return [Program] the assembled program
+    def assemble(source)
+      statements = parse(source)
+      labels, layout = resolve_layout(statements)
+      build_program(statements, labels, layout)
+    end
+
+    private
+
+    # Parses source text into line-oriented statements.
+    #
+    # @param source [String] the assembly source
+    # @return [Array<Statement>] the parsed statements
+    def parse(source)
+      source.each_line.with_index(1).filter_map do |line, line_number|
+        stripped = line.sub(/;.*/, '').strip
+        next if stripped.empty?
+
+        label = nil
+        if stripped =~ /\A([A-Za-z_][A-Za-z0-9_]*):/
+          label = Regexp.last_match(1)
+          stripped = stripped[Regexp.last_match(0).length..].to_s.strip
+        end
+
+        if stripped.empty?
+          Statement.new(line_number:, label:, raw: line.rstrip)
+        else
+          name, argument = stripped.split(/\s+/, 2)
+          kind = name.start_with?('.') ? :directive : :instruction
+          Statement.new(
+            line_number:,
+            label:,
+            kind:,
+            name: name.downcase,
+            argument: argument&.strip,
+            raw: line.rstrip
+          )
+        end
+      end
+    end
+
+    # Resolves labels and instruction sizes until the layout converges.
+    #
+    # @param statements [Array<Statement>] the parsed statements
+    # @return [Array<(Hash, Hash)>] labels and per-line layout metadata
+    def resolve_layout(statements)
+      previous_state = nil
+
+      MAX_PASSES.times do
+        pc = DEFAULT_ORIGIN
+        labels = {}
+        layout = {}
+
+        statements.each_with_index do |statement, index|
+          register_label(statement, labels, pc)
+          next unless statement.kind
+
+          case statement.kind
+          when :directive
+            pc = layout_directive(statement, layout, index, labels, pc)
+          when :instruction
+            mode = select_mode(statement, labels, pc, strict: false)
+            size = instruction_size(mode)
+            layout[index] = { address: pc, mode:, size: }
+            pc = (pc + size) & 0xffff
+          end
+        end
+
+        current_state = [labels, layout]
+        return current_state if current_state == previous_state
+
+        previous_state = current_state
+      end
+
+      raise AssemblyError, "Assembly did not converge after #{MAX_PASSES} passes"
+    end
+
+    # Emits the final bytecode into loadable segments.
+    #
+    # @param statements [Array<Statement>] the parsed statements
+    # @param labels [Hash{String => Integer}] resolved labels
+    # @param layout [Hash{Integer => Hash}] resolved instruction layout
+    # @return [Program] the assembled program
+    def build_program(statements, labels, layout)
+      pc = DEFAULT_ORIGIN
+      current_start = pc
+      current_bytes = []
+      segments = []
+
+      statements.each_with_index do |statement, index|
+        next unless statement.kind
+
+        case statement.kind
+        when :directive
+          case statement.name
+          when '.org'
+            flush_segment(segments, current_start, current_bytes)
+            pc = evaluate(statement.argument, labels, pc, strict: true) & 0xffff
+            current_start = pc
+            current_bytes = []
+          when '.byte'
+            bytes = split_operands(statement.argument).map { |operand| evaluate(operand, labels, pc, strict: true) & 0xff }
+            current_bytes.concat(bytes)
+            pc = (pc + bytes.length) & 0xffff
+          when '.word'
+            words = split_operands(statement.argument).map { |operand| evaluate(operand, labels, pc, strict: true) & 0xffff }
+            words.each do |word|
+              current_bytes << (word & 0xff)
+              current_bytes << (word >> 8)
+            end
+            pc = (pc + (words.length * 2)) & 0xffff
+          end
+        when :instruction
+          mode = layout.fetch(index).fetch(:mode)
+          bytes = encode_instruction(statement, mode, labels, pc)
+          current_bytes.concat(bytes)
+          pc = (pc + bytes.length) & 0xffff
+        end
+      end
+
+      flush_segment(segments, current_start, current_bytes)
+      Program.new(segments:, labels:, entry_point: determine_entry_point(statements, labels, layout, segments))
+    end
+
+    # Records a label at the current location counter.
+    #
+    # @param statement [Statement] the current statement
+    # @param labels [Hash{String => Integer}] the label table
+    # @param pc [Integer] the current location counter
+    # @return [void]
+    def register_label(statement, labels, pc)
+      return unless statement.label
+
+      raise AssemblyError, format_error(statement, "Duplicate label #{statement.label}") if labels.key?(statement.label)
+
+      labels[statement.label] = pc
+    end
+
+    # Reserves space for a directive during layout resolution.
+    #
+    # @param statement [Statement] the directive statement
+    # @param layout [Hash] layout metadata
+    # @param index [Integer] the statement index
+    # @param labels [Hash{String => Integer}] currently known labels
+    # @param pc [Integer] the current location counter
+    # @return [Integer] the updated location counter
+    def layout_directive(statement, layout, index, labels, pc)
+      raise AssemblyError, format_error(statement, "Unknown directive #{statement.name}") unless DIRECTIVES.include?(statement.name)
+
+      case statement.name
+      when '.org'
+        new_pc = evaluate(statement.argument, labels, pc, strict: true) & 0xffff
+        layout[index] = { address: new_pc, size: 0 }
+        new_pc
+      when '.byte'
+        count = split_operands(statement.argument).length
+        layout[index] = { address: pc, size: count }
+        (pc + count) & 0xffff
+      when '.word'
+        count = split_operands(statement.argument).length
+        layout[index] = { address: pc, size: count * 2 }
+        (pc + (count * 2)) & 0xffff
+      end
+    end
+
+    # Encodes a single instruction into bytes.
+    #
+    # @param statement [Statement] the instruction statement
+    # @param mode [Symbol] the resolved addressing mode
+    # @param labels [Hash{String => Integer}] resolved labels
+    # @param pc [Integer] the instruction address
+    # @return [Array<Integer>] the encoded instruction bytes
+    def encode_instruction(statement, mode, labels, pc)
+      mnemonic = statement.name.to_sym
+      opcode = OPCODES_BY_MNEMONIC.fetch(mnemonic).fetch(mode)
+      value = operand_value(statement, labels, pc, strict: true)
+      bytes = [opcode]
+
+      case mode
+      when :implied, :accumulator
+        bytes
+      when :immediate, :zero_page, :zero_page_x, :zero_page_y, :indirect_x, :indirect_y
+        bytes << (value & 0xff)
+      when :relative
+        offset = value - ((pc + 2) & 0xffff)
+        raise AssemblyError, format_error(statement, "Branch target out of range: #{statement.argument}") unless (-128..127).cover?(offset)
+
+        bytes << (offset & 0xff)
+      when :absolute, :absolute_x, :absolute_y, :indirect
+        bytes << (value & 0xff)
+        bytes << ((value >> 8) & 0xff)
+      end
+    end
+
+    # Selects the final addressing mode for an instruction.
+    #
+    # @param statement [Statement] the instruction statement
+    # @param labels [Hash{String => Integer}] known labels
+    # @param pc [Integer] the current instruction address
+    # @param strict [Boolean] whether unknown labels should raise
+    # @return [Symbol] the resolved addressing mode
+    def select_mode(statement, labels, pc, strict:)
+      mnemonic = statement.name.to_sym
+      modes = OPCODES_BY_MNEMONIC.fetch(mnemonic, nil)
+      raise AssemblyError, format_error(statement, "Unknown instruction #{statement.name}") unless modes
+
+      syntax, expression = operand_syntax(statement)
+      value = expression && evaluate(expression, labels, pc, strict:)
+
+      case syntax
+      when :implied, :accumulator, :immediate, :indirect, :indirect_x, :indirect_y
+        ensure_mode!(statement, modes, syntax)
+      when :relative
+        ensure_mode!(statement, modes, :relative)
+      when :bare
+        choose_direct_mode(statement, modes, value, :zero_page, :absolute)
+      when :indexed_x
+        choose_direct_mode(statement, modes, value, :zero_page_x, :absolute_x)
+      when :indexed_y
+        choose_direct_mode(statement, modes, value, :zero_page_y, :absolute_y)
+      else
+        raise AssemblyError, format_error(statement, "Unsupported operand syntax #{statement.argument.inspect}")
+      end
+    end
+
+    # Parses an operand into a syntax family and expression text.
+    #
+    # @param statement [Statement] the instruction statement
+    # @return [Array<(Symbol, String, nil)>] syntax kind and expression text
+    def operand_syntax(statement)
+      operand = statement.argument
+      return [:implied, nil] if operand.nil? || operand.empty?
+      return [:accumulator, nil] if operand.casecmp('a').zero?
+
+      return [:relative, operand] if BRANCH_MNEMONICS.include?(statement.name.to_sym)
+
+      case operand
+      when /\A#\s*(.+)\z/
+        [:immediate, Regexp.last_match(1)]
+      when /\A\(\s*(.+)\s*,\s*x\s*\)\z/i
+        [:indirect_x, Regexp.last_match(1)]
+      when /\A\(\s*(.+)\s*\)\s*,\s*y\z/i
+        [:indirect_y, Regexp.last_match(1)]
+      when /\A\(\s*(.+)\s*\)\z/
+        [:indirect, Regexp.last_match(1)]
+      when /\A(.+)\s*,\s*x\z/i
+        [:indexed_x, Regexp.last_match(1)]
+      when /\A(.+)\s*,\s*y\z/i
+        [:indexed_y, Regexp.last_match(1)]
+      else
+        [:bare, operand]
+      end
+    end
+
+    # Evaluates an instruction operand expression if one is present.
+    #
+    # @param statement [Statement] the instruction statement
+    # @param labels [Hash{String => Integer}] resolved labels
+    # @param pc [Integer] the current instruction address
+    # @param strict [Boolean] whether unknown labels should raise
+    # @return [Integer, nil] the evaluated operand
+    def operand_value(statement, labels, pc, strict:)
+      _syntax, expression = operand_syntax(statement)
+      expression && evaluate(expression, labels, pc, strict:)
+    end
+
+    # Chooses between short and long addressing forms.
+    #
+    # @param statement [Statement] the instruction statement
+    # @param modes [Hash{Symbol => Integer}] supported modes for the mnemonic
+    # @param value [Integer, nil] the evaluated operand
+    # @param short_mode [Symbol] the zero-page form
+    # @param long_mode [Symbol] the absolute form
+    # @return [Symbol] the selected mode
+    def choose_direct_mode(statement, modes, value, short_mode, long_mode)
+      short_supported = modes.key?(short_mode)
+      long_supported = modes.key?(long_mode)
+
+      if short_supported && value && fits_byte?(value)
+        short_mode
+      elsif long_supported
+        long_mode
+      elsif short_supported
+        if value && !fits_byte?(value)
+          raise AssemblyError,
+                format_error(statement, "Operand does not fit #{short_mode}: #{statement.argument}")
+        end
+
+        short_mode
+      else
+        supported = modes.keys.join(', ')
+        raise AssemblyError, format_error(statement, "Unsupported addressing mode for #{statement.name}; supported modes: #{supported}")
+      end
+    end
+
+    # Verifies that a mnemonic supports a required addressing mode.
+    #
+    # @param statement [Statement] the instruction statement
+    # @param modes [Hash{Symbol => Integer}] supported modes
+    # @param mode [Symbol] the required mode
+    # @return [Symbol] the mode when supported
+    def ensure_mode!(statement, modes, mode)
+      return mode if modes.key?(mode)
+
+      raise AssemblyError, format_error(statement, "Unsupported addressing mode #{mode} for #{statement.name}")
+    end
+
+    # Returns the encoded size of an instruction by addressing mode.
+    #
+    # @param mode [Symbol] the addressing mode
+    # @return [Integer] the instruction size in bytes
+    def instruction_size(mode)
+      case mode
+      when :implied, :accumulator
+        1
+      when :immediate, :zero_page, :zero_page_x, :zero_page_y, :indirect_x, :indirect_y, :relative
+        2
+      when :absolute, :absolute_x, :absolute_y, :indirect
+        3
+      else
+        raise AssemblyError, "Unknown instruction size for #{mode}"
+      end
+    end
+
+    # Splits a comma-separated operand list while preserving nested expressions.
+    #
+    # @param text [String, nil] the raw operand text
+    # @return [Array<String>] the individual operands
+    def split_operands(text)
+      return [] if text.nil? || text.empty?
+
+      operands = []
+      depth = 0
+      current = +''
+
+      text.each_char do |char|
+        case char
+        when ','
+          if depth.zero?
+            operands << current.strip
+            current.clear
+          else
+            current << char
+          end
+        when '('
+          depth += 1
+          current << char
+        when ')'
+          depth -= 1
+          current << char
+        else
+          current << char
+        end
+      end
+
+      operands << current.strip unless current.empty?
+      operands.reject(&:empty?)
+    end
+
+    # Evaluates a numeric expression used by directives or operands.
+    #
+    # @param expression [String] the expression text
+    # @param labels [Hash{String => Integer}] resolved labels
+    # @param pc [Integer] the current assembly address
+    # @param strict [Boolean] whether unknown labels should raise
+    # @return [Integer, nil] the computed expression value
+    def evaluate(expression, labels, pc, strict:)
+      tokens = tokenize(expression)
+      value, position = parse_expression(tokens, 0, labels, pc, strict:)
+      raise AssemblyError, "Unexpected token #{tokens[position]}" if position < tokens.length && strict
+
+      value
+    end
+
+    # Tokenizes a simple arithmetic expression.
+    #
+    # @param expression [String] the expression to tokenize
+    # @return [Array<String>] the tokens
+    def tokenize(expression)
+      tokens = []
+      index = 0
+
+      while index < expression.length
+        char = expression[index]
+
+        if char.match?(/\s/)
+          index += 1
+        elsif %w[( ) + - < > *].include?(char)
+          tokens << char
+          index += 1
+        elsif char == '$'
+          match = expression[index..].match(/\A\$[0-9a-fA-F]+/)
+          raise AssemblyError, "Invalid hex literal in #{expression.inspect}" unless match
+
+          tokens << match[0]
+          index += match[0].length
+        elsif char == '%'
+          match = expression[index..].match(/\A%[01]+/)
+          raise AssemblyError, "Invalid binary literal in #{expression.inspect}" unless match
+
+          tokens << match[0]
+          index += match[0].length
+        elsif char.match?(/\d/)
+          match = expression[index..].match(/\A\d+/)
+          tokens << match[0]
+          index += match[0].length
+        elsif char == "'" && expression[index + 2] == "'"
+          tokens << expression[index, 3]
+          index += 3
+        elsif char.match?(/[A-Za-z_]/)
+          match = expression[index..].match(/\A[A-Za-z_][A-Za-z0-9_]*/)
+          tokens << match[0]
+          index += match[0].length
+        else
+          raise AssemblyError, "Unexpected character #{char.inspect} in #{expression.inspect}"
+        end
+      end
+
+      tokens
+    end
+
+    # Parses addition and subtraction.
+    #
+    # @param tokens [Array<String>] the token stream
+    # @param position [Integer] the current token index
+    # @param labels [Hash{String => Integer}] resolved labels
+    # @param pc [Integer] the current assembly address
+    # @param strict [Boolean] whether unknown labels should raise
+    # @return [Array<(Integer, nil, Integer)>] the value and next token index
+    def parse_expression(tokens, position, labels, pc, strict:)
+      value, position = parse_unary(tokens, position, labels, pc, strict:)
+
+      while %w[+ -].include?(tokens[position])
+        operator = tokens[position]
+        rhs, next_position = parse_unary(tokens, position + 1, labels, pc, strict:)
+        value = nil_value_math(value, rhs, operator)
+        position = next_position
+      end
+
+      [value, position]
+    end
+
+    # Parses unary operators and primary expressions.
+    #
+    # @param tokens [Array<String>] the token stream
+    # @param position [Integer] the current token index
+    # @param labels [Hash{String => Integer}] resolved labels
+    # @param pc [Integer] the current assembly address
+    # @param strict [Boolean] whether unknown labels should raise
+    # @return [Array<(Integer, nil, Integer)>] the value and next token index
+    def parse_unary(tokens, position, labels, pc, strict:)
+      token = tokens[position]
+      raise AssemblyError, 'Unexpected end of expression' unless token
+
+      case token
+      when '+'
+        parse_unary(tokens, position + 1, labels, pc, strict:)
+      when '-'
+        value, next_position = parse_unary(tokens, position + 1, labels, pc, strict:)
+        [value&.-@, next_position]
+      when '<'
+        value, next_position = parse_unary(tokens, position + 1, labels, pc, strict:)
+        [value && (value & 0xff), next_position]
+      when '>'
+        value, next_position = parse_unary(tokens, position + 1, labels, pc, strict:)
+        [value && ((value >> 8) & 0xff), next_position]
+      when '('
+        value, next_position = parse_expression(tokens, position + 1, labels, pc, strict:)
+        raise AssemblyError, 'Missing closing parenthesis' unless tokens[next_position] == ')'
+
+        [value, next_position + 1]
+      else
+        [parse_primary(token, labels, pc, strict:), position + 1]
+      end
+    end
+
+    # Parses a numeric literal, current address marker, or label reference.
+    #
+    # @param token [String] the current token
+    # @param labels [Hash{String => Integer}] resolved labels
+    # @param pc [Integer] the current assembly address
+    # @param strict [Boolean] whether unknown labels should raise
+    # @return [Integer, nil] the resolved value
+    def parse_primary(token, labels, pc, strict:)
+      case token
+      when /\A\$[0-9a-fA-F]+\z/
+        token[1..].to_i(16)
+      when /\A%[01]+\z/
+        token[1..].to_i(2)
+      when /\A\d+\z/
+        token.to_i
+      when /\A'.'\z/
+        token[1].ord
+      when '*'
+        pc
+      else
+        return labels[token] if labels.key?(token)
+        raise AssemblyError, "Unknown symbol #{token}" if strict
+
+        nil
+      end
+    end
+
+    # Applies arithmetic while allowing unresolved values during non-strict passes.
+    #
+    # @param lhs [Integer, nil] the left-hand side
+    # @param rhs [Integer, nil] the right-hand side
+    # @param operator [String] `+` or `-`
+    # @return [Integer, nil] the arithmetic result
+    def nil_value_math(lhs, rhs, operator)
+      return nil if lhs.nil? || rhs.nil?
+
+      operator == '+' ? lhs + rhs : lhs - rhs
+    end
+
+    # Determines whether a value fits in an unsigned byte.
+    #
+    # @param value [Integer] the value to test
+    # @return [Boolean] true when the value fits `0x00..0xFF`
+    def fits_byte?(value)
+      value.between?(0x00, 0xff)
+    end
+
+    # Appends a finished segment when it contains emitted bytes.
+    #
+    # @param segments [Array<Segment>] the collected segments
+    # @param start_address [Integer] the segment origin
+    # @param bytes [Array<Integer>] the emitted bytes
+    # @return [void]
+    def flush_segment(segments, start_address, bytes)
+      return if bytes.empty?
+
+      segments << Segment.new(start_address:, bytes: bytes.dup)
+    end
+
+    # Chooses the program entry point for reset/load purposes.
+    #
+    # Preference order:
+    # - a label named `start`
+    # - the address of the first instruction
+    # - the first emitted segment address
+    # - the default origin
+    #
+    # @param statements [Array<Statement>] parsed source statements
+    # @param labels [Hash{String => Integer}] resolved labels
+    # @param layout [Hash{Integer => Hash}] resolved instruction layout
+    # @param segments [Array<Segment>] emitted segments
+    # @return [Integer] the chosen entry point
+    def determine_entry_point(statements, labels, layout, segments)
+      return labels['start'] if labels.key?('start')
+
+      first_instruction_index = statements.find_index { |statement| statement.kind == :instruction }
+      return layout.fetch(first_instruction_index).fetch(:address) if first_instruction_index
+
+      segments.first&.start_address || DEFAULT_ORIGIN
+    end
+
+    # Formats an error message with source line context.
+    #
+    # @param statement [Statement] the statement that failed
+    # @param message [String] the underlying error
+    # @return [String] the contextualized error message
+    def format_error(statement, message)
+      "Line #{statement.line_number}: #{message} (#{statement.raw.strip})"
+    end
+  end
+end