HBC Reader Architecture

type HBCReader struct {
    Header                   HBCHeader
    FunctionHeaders          []any // SmallFunctionHeader | LargeFunctionHeader
    FunctionIDToExcHandlers  map[int][]ExceptionHandlerInfo
    FunctionIDToDebugOffsets map[int]DebugOffsets
    
    StringKinds              []StringKind
    IdentifierHashes         []uint32
    SmallStringTable         []SmallStringTableEntry
    OverflowStringTable      []OffsetLengthPair
    Strings                  []string
    
    Arrays       []byte
    ObjectKeys   []byte
    ObjectValues []byte
    BigIntValues []int64
    
    RegExpTable   []OffsetLengthPair
    RegExpStorage *bytes.Reader
    
    CjsModules      []any // uint32 | SymbolOffsetPair
    FunctionSources []FunctionSourceEntry
    
    DebugInfoHeader      DebugInfoHeader
    DebugStringTable     []OffsetLengthPair
    DebugStringStorage   *bytes.Reader
    DebugFileRegions     []DebugFileRegion
    SourcesDataStorage   *bytes.Reader
    ScopeDescDataStorage *bytes.Reader
    TextifiedDataStorage *bytes.Reader
    StringTableStorage   *bytes.Reader
    
    FileBuffer *bytes.Reader
    ParserModule *ParserModule // Version-specific opcode definitions
}

func (h *HBCReader) ReadWholeFile(file io.ReadSeeker) error {
    // 1. Load entire file into memory
    fileData, err := io.ReadAll(file)
    h.FileBuffer = bytes.NewReader(fileData)
    
    // 2. Parse header and verify SHA1 (bcv >= 75)
    if err := h.ReadHeader(); err != nil {
        return err
    }
    
    // 3. Initialize version-specific parser module
    if err := h.InitParserModule(); err != nil {
        return err
    }
    
    // 4. Parse all sections in order
    h.ReadFunctions()
    h.ReadStringKinds()
    h.ReadIdentifierHashes()
    h.ReadSmallStringTable()
    h.ReadOverflowStringTable()
    h.ReadStringStorage()
    h.ReadArrays()
    if h.Header.Version >= 87 {
        h.ReadBigInts()
    }
    h.ReadRegExp()
    h.ReadCjsModules()
    if h.Header.Version >= 84 {
        h.ReadFunctionSources()
    }
    h.ReadDebugInfo()
    
    return nil
}

type SmallFunctionHeader struct {
    Offset                 uint32 // 25 bits (max 33MB bytecode offset)
    ParamCount             uint8  // 7 bits (max 127 params)
    BytecodeSizeInBytes    uint16 // 15 bits (max 32KB bytecode)
    FunctionName           uint32 // 17 bits (string table index)
    InfoOffset             uint32 // 25 bits (debug info offset)
    FrameSize              uint8  // 7 bits (max 127 registers)
    EnvironmentState       uint8
    HighestReadCacheIndex  uint8
    HighestWriteCacheIndex uint8
    ProhibitInvoke         uint8 // 2 bits
    StrictMode             bool  // 1 bit
    HasExceptionHandler    bool  // 1 bit
    HasDebugInfo           bool  // 1 bit
    Overflowed             bool  // 1 bit - triggers LargeFunctionHeader
    Unused                 uint8 // 2 bits
}

type LargeFunctionHeader struct {
    Offset                 uint32 // Full 32 bits
    ParamCount             uint32 // Full 32 bits
    BytecodeSizeInBytes    uint32 // Full 32 bits (max 4GB)
    FunctionName           uint32 // Full 32 bits
    InfoOffset             uint32 // Full 32 bits
    FrameSize              uint32 // Full 32 bits
    EnvironmentSize        uint32
    HighestReadCacheIndex  uint8
    HighestWriteCacheIndex uint8
    // Same flags as SmallFunctionHeader
}

if sste.Length == 0xff {
    overflowIndex := int(sste.Offset)
    overflowInfo := h.OverflowStringTable[overflowIndex]
    offset = int64(overflowInfo.Offset)  // Actual offset (32 bits)
    length = overflowInfo.Length          // Actual length (32 bits)
}

if isUTF16 {
    // Read 2 bytes per character
    uint16Data := make([]uint16, length)
    for j := uint32(0); j < length; j++ {
        uint16Data[j] = uint16(stringBytes[j*2]) | uint16(stringBytes[j*2+1])<<8
    }
    
    // Handle surrogate pairs for code points > U+FFFF
    for j := 0; j < len(uint16Data); j++ {
        r := rune(uint16Data[j])
        if r >= 0xD800 && r <= 0xDBFF && j+1 < len(uint16Data) {
            if surrogate := uint16Data[j+1]; surrogate >= 0xDC00 && surrogate <= 0xDFFF {
                // Combine high + low surrogates
                r = (r-0xD800)<<10 | (rune(surrogate) - 0xDC00)
                j++ // Skip low surrogate
            }
        }
        sb.WriteRune(r)
    }
} else {
    // Latin-1: each byte is a rune
    for _, b := range stringBytes {
        sb.WriteRune(rune(b))
    }
}

func GetParser(bcv int) *ParserModule {
    parserModuleTable := map[int]*ParserModule{
        84: {bcv84.OpcodeToInstruction, bcv84.NameToInstruction, bcv84.BuiltinFunctionNames},
        85: {bcv85.OpcodeToInstruction, bcv85.NameToInstruction, bcv85.BuiltinFunctionNames},
        89: {bcv89.OpcodeToInstruction, bcv89.NameToInstruction, bcv89.BuiltinFunctionNames},
        90: {bcv90.OpcodeToInstruction, bcv90.NameToInstruction, bcv90.BuiltinFunctionNames},
        94: {bcv94.OpcodeToInstruction, bcv94.NameToInstruction, bcv94.BuiltinFunctionNames},
        96: {bcv96.OpcodeToInstruction, bcv96.NameToInstruction, bcv96.BuiltinFunctionNames},
    }
    
    // Select highest parser version <= bcv
    // E.g., bcv 92 uses parser 90
    var maxVersion int
    for version, module := range parserModuleTable {
        if version <= bcv && version > maxVersion {
            maxVersion = version
            parser = module
        }
    }
    return parser
}

func ParseHBCBytecode(functionHeader any, hbcReader *HBCReader) ([]*ParsedInstruction, error) {
    // 1. Extract function offset and size from header
    offset := int(header.Offset)
    bytecodeSizeInBytes := int(header.BytecodeSizeInBytes)
    
    // 2. Seek to function bytecode in file
    hbcReader.FileBuffer.Seek(int64(offset), io.SeekStart)
    
    // 3. Read raw bytecode bytes
    bytecode := make([]byte, bytecodeSizeInBytes)
    io.ReadFull(hbcReader.FileBuffer, bytecode)
    
    // 4. Decode instructions
    buf := bytes.NewReader(bytecode)
    for {
        var opcode byte
        binary.Read(buf, binary.LittleEndian, &opcode)
        
        // Look up instruction definition
        inst := hbcReader.ParserModule.OpcodeToInstruction[int(opcode)]
        
        // Read operands based on instruction definition
        args := make([]any, len(inst.Operands))
        for i, operand := range inst.Operands {
            switch operand.Type.Kind {
            case "uint8_t":
                var val uint8
                binary.Read(buf, binary.LittleEndian, &val)
                args[i] = uint(val)
            case "uint16_t":
                var val uint16
                binary.Read(buf, binary.LittleEndian, &val)
                args[i] = uint(val)
            // ... handle all operand types
            }
        }
        
        instructions = append(instructions, &ParsedInstruction{
            Inst:        inst,
            Args:        args,
            OriginalPos: currentPos,
        })
    }
    return instructions, nil
}