ton-source-map/README.md

TypeScript type definitions and functions for TON Source Map format used by Tolk and FunC compilers

# TON Source Map

[![CI](https://github.com/i582/ton-source-map/workflows/CI/badge.svg)](https://github.com/i582/ton-source-map/actions)

TypeScript type definitions and utilities for the TON Source Map format used by Tolk and FunC compilers.

## What is TON Source Map?

TON Source Map provides debugging capabilities for smart contracts compiled to TVM (TON Virtual Machine).
It enables source-level debugging by mapping between:

- **High-level source code** (Tolk/FunC) and **TVM bitcode** (Cells)
- **Debug locations** with variable state information
- **Source files** and their compiled representations

### Architecture

The source map consists of two main components:

#### High-Level Mapping

Maps DEBUGMARK IDs (debug sections) to high-level language constructs:

- Source code locations (file, line, column)
- Variable states at each debug point
- Function context and inlining information
- AST node types and execution context

#### Assembly Mapping

Maps TVM Cells to assembly instructions:

- Cell hash to instruction sequences
- Instruction locations and debug sections
- Offset-based navigation in bitcode

### How Mappings Work Together

The two mappings form a complete debugging bridge between TVM bitcode and source code through **debug sections**:

1. **High-level → Debug Sections**: Each `HighLevelSourceMapEntry` has an `idx` field
   that represents a debug section number.
   This connects source locations to logical code blocks.

2. **Assembly → Debug Sections**: Each `InstructionInfo` contains a `debugSections` array that links TVM instructions to
   the same debug section numbers.

3. **Complete Mapping**: When TVM executes an instruction, you can:
    - Find the instruction in assembly mapping by (cell hash + offset)
    - Get debug section numbers from that instruction
    - Look up corresponding source locations in high-level mapping

**Example flow:**

```
TVM Execution Data (hash + offset)
    ↓ findInstructionInfo()
Assembly Mapping → InstructionInfo.debugSections[]
    ↓ findHighlevelLocationBySection()
High-Level Mapping → HighLevelSourceMapEntry.loc (file, line, column)
```

This architecture enables bidirectional debugging: from bitcode to source code and vice versa.

### Usage

```typescript
import {SourceMap, findHighlevelLocations} from "ton-source-map"

// Find source location from TVM execution data
const locations = findHighlevelLocations(sourceMap, cellHash, offset)
```

## Development

This project uses [Corepack](https://nodejs.org/api/corepack.html) to manage Yarn version. Make sure to enable it first:

```bash
# Enable corepack (one time setup)
corepack enable

# Run tests
yarn test

# Run linter check
yarn fmt:check

# Run full pre-commit checks
yarn precommit
```

## License

MIT