func-contract-analyzer/README.md

FunC Smart Contract Static Analyzer - Storage, Call Graph, Function References, Global Variables, and Constant Analysis

# FunC Smart Contract Analyzer

[![npm version](https://badge.fury.io/js/func-contract-analyzer.svg)](https://www.npmjs.com/package/func-contract-analyzer)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)

Static analyzer for TON blockchain FunC smart contracts. Provides comprehensive analysis of call graphs, constants, and dependencies with LLM-optimized JSON output.

## Why This Tool Matters

**The Problem**: Modern FunC contracts use complex include hierarchies and modular architecture. Traditional tools miss critical dependencies or incorrectly identify functional modules as deployable contracts.

**Real Example**: SwapCoffee's pool contracts
```bash
# This file looks like a contract but only contains includes:
pool_constant_product.fc:
  #include "pool/amm/constant_product.fc"
  #include "pool/include/jetton_based.fc"  
  #include "pool/include/recv_internal.fc"

# Without proper analysis, you'd miss jetton_based.fc entirely
```

**Our Solution**: Reverse thinking algorithm correctly identifies `pool_constant_product.fc` as the deployable contract while including all its dependencies like `jetton_based.fc` and `compare_fractions()`.

## Quick Start

```bash
# Analyze any TON contract instantly
npx func-contract-analyzer@latest path/to/contract.fc

# Generate JSON for LLM analysis
npx func-contract-analyzer@latest contract.fc --mode json -o analysis.json

# Analyze entire project with filtering
npx func-contract-analyzer@latest project/ --exclude "test/**,mock/**"
```

## Real-World Impact

### SwapCoffee Analysis
**Before**: Missed `jetton_based.fc` module containing critical `compare_fractions()` function  
**After**: Complete dependency analysis including all 10 pool contracts

### Torch DEX Analysis  
**Result**: 9 true entry points correctly identified (pools, vaults, factory)  
**Value**: No false positives from functional modules

### Complex Include Chains
```bash
pool_constant_product.fc → jetton_based.fc → math.fc → compare_fractions()
```
**Complete dependency tree captured in single analysis**

## Core Features

### 🎯 True Entry Point Detection
Uses reverse thinking algorithm to distinguish deployable contracts from library modules:
- ✅ `pool_constant_product.fc` → True entry point (deployable)
- ❌ `pool/include/recv_internal.fc` → Functional module (library)

### 📊 Complete Call Graph Analysis  
Visual tree representation of function calls:
```
recv_internal
├── deposit_liquidity
│   ├── compare_fractions
│   └── add_liquidity_impl
└── swap_internal
    └── perform_swap
```

### 🔍 Smart Constant Resolution
Resolves complex constant expressions and dependencies:
```funC
const int base_fee = 1000;
const int swap_fee = base_fee * 3;  // Correctly evaluates to 3000
```

### 📋 LLM-Optimized Output
JSON format designed for AI vulnerability analysis with complete source code and metadata.

## Output Modes

### Console Mode (Default)
```bash
func-analyzer contract.fc
```
Beautiful formatted output for development and debugging.

### JSON Mode  
```bash
func-analyzer contract.fc --mode json -o analysis.json
```
Complete structured data including:
- All functions with source code
- Complete call graph with locations  
- Resolved constants with values
- File dependency tree

## Installation

### NPX (Recommended)
```bash
npx func-contract-analyzer@latest path/to/contract.fc
```

### Global Installation
```bash
npm install -g func-contract-analyzer
func-analyzer path/to/contract.fc
```

### From Source
```bash
git clone https://github.com/alan890104/func-analyzer.git
cd func-analyzer
bun install
bun run src/main.ts contract.fc
```

## CLI Reference

```bash
Usage: func-analyzer [options] <contract-path>

Arguments:
  contract-path         Path to FunC contract file or directory

Options:
  --mode <mode>         console | json (default: console)
  --exclude <patterns>  Comma-separated gitignore-style patterns
  --max-depth <n>       Maximum call tree depth  
  -o, --output <file>   Output file (required for JSON mode)
  --wasm-path <path>    Custom tree-sitter-func.wasm path
  -q, --quiet           Suppress output except results
  -h, --help            Show help

Examples:
  func-analyzer contract.fc
  func-analyzer project/ --exclude "test/**,*mock*"
  func-analyzer contract.fc --mode json -o analysis.json
```

## Architecture

Built on **Clean Architecture** principles:
- **Interfaces**: TypeScript contracts defining behavior
- **Implementations**: Business logic with dependency injection  
- **Universal Analysis**: No hardcoded patterns, works with any TON project
- **Tree-sitter Parsing**: Robust AST-based analysis, no regex

### Key Components
```
src/
├── implementations/
│   ├── FileManager.ts           # Reverse thinking algorithm
│   ├── ContractAnalyzer.ts      # Main analysis coordinator  
│   ├── CallGraphAnalyzer.ts     # Function relationships
│   └── ConstantsResolver.ts     # Expression evaluation
├── interfaces/                  # Type definitions
└── grammer/                     # Tree-sitter FunC grammar
```

## Development

### Requirements
- **Bun runtime** (required for performance)
- TypeScript 5.0+

### Commands  
```bash
bun install                      # Install dependencies
bun run src/main.ts contract.fc  # Development mode
bun test                         # Run 150+ tests
bun run build:main               # Production build
```

### Testing
All tests use real tree-sitter parsing with actual FunC contracts:
- **150 tests** covering all major TON projects
- **Real filesystem testing** with dependency injection
- **No mocks** - validates against actual contract parsing

## Recent Updates

### v0.8.0 - Reverse Thinking Algorithm
- ✅ **Fixed duplicate analysis**: Functional modules no longer appear as contracts
- ✅ **True entry point detection**: Correctly identifies deployable vs library files  
- ✅ **SwapCoffee support**: Now properly analyzes complex modular contracts
- ✅ **150 tests pass**: Full backward compatibility maintained

## Contributing

See `CLAUDE.md` for development guidelines. The project follows Clean Architecture with dependency injection and extensive test coverage.

## License

MIT License - see LICENSE file for details.

---

**Built for security researchers and TON developers who need comprehensive contract analysis.**