# Scripts Reference Guide

Complete reference for all development, testing, and audit scripts.

## Table of Contents

- [Main Development Script](#main-development-script-devsh)
- [Testing Scripts](#testing-scripts)
- [Audit Scripts](#audit-scripts)
- [Contract Scripts](#contract-scripts)
- [Utility Scripts](#utility-scripts)

## Main Development Script: `dev.sh`

**Location:** `scripts/dev.sh`

**Purpose:** Unified interface for all development operations. Enforces containerized development workflow per SPEC.md.

### Usage

```bash
./scripts/dev.sh <command> [args]
```

### Commands

#### Container Management

```bash
./scripts/dev.sh up          # Start all dev containers
./scripts/dev.sh down        # Stop all dev containers
./scripts/dev.sh restart     # Restart dev containers
./scripts/dev.sh ps          # Show container status
./scripts/dev.sh logs <svc>  # View logs for service
```

#### Container Access

```bash
./scripts/dev.sh go          # Enter Go container (interactive shell)
./scripts/dev.sh python      # Enter Python container
./scripts/dev.sh foundry     # Enter Foundry container
```

#### Build & Test

```bash
./scripts/dev.sh build       # Build Go application
./scripts/dev.sh test <type> # Run tests (see Testing section)
```

#### Audit & Quality

```bash
./scripts/dev.sh audit            # Comprehensive code audit
./scripts/dev.sh check-docs       # Documentation coverage
./scripts/dev.sh check-compliance # SPEC.md compliance
```

#### Contract Operations

```bash
./scripts/dev.sh forge-build # Build Solidity contracts
./scripts/dev.sh forge-test  # Run contract tests
./scripts/dev.sh bindings    # Generate Go bindings
```

#### Cleanup

```bash
./scripts/dev.sh clean   # Remove build artifacts
./scripts/dev.sh reset   # Stop containers + clean
```

---

## Testing Scripts

### `test.sh` - Comprehensive Test Suite

**Location:** `scripts/test.sh`

**Purpose:** Run all types of tests with proper containerization.

#### Usage

```bash
./scripts/test.sh [type] [verbose]
```

#### Test Types

```bash
# All tests (unit + integration + race + contracts)
./scripts/test.sh all

# Unit tests only
./scripts/test.sh unit

# Integration tests
./scripts/test.sh integration

# Race detection
./scripts/test.sh race

# Benchmarks
./scripts/test.sh bench

# Coverage report
./scripts/test.sh coverage

# Specific package
./scripts/test.sh pkg sequencer

# Contract tests
./scripts/test.sh contracts
```

#### Verbose Mode

```bash
./scripts/test.sh unit true      # Verbose unit tests
./scripts/test.sh all v          # Verbose all tests
```

#### Output

- **Exit 0:** All tests passed
- **Exit 1:** One or more test suites failed

#### Coverage Report

When running `coverage` type:
- Generates `coverage/coverage.out`
- Generates `coverage/coverage.html` (open in browser)
- Prints coverage percentage

**Target:** >70% coverage

---

## Audit Scripts

### `audit.sh` - Codebase Audit

**Location:** `scripts/audit.sh`

**Purpose:** Comprehensive code quality, security, and compliance audit.

#### Usage

```bash
./scripts/audit.sh
```

#### What It Checks

**1. SPEC.md Compliance**
- Hardcoded function selectors
- HTTP RPC usage in sequencer
- Blocking operations in hot paths
- Manual ABI files

**2. Go Code Quality**
- `go vet` issues
- TODO/FIXME comments
- panic() in production code

**3. Security**
- Hardcoded private keys
- SQL injection risks
- Command injection
- Unsafe pointer usage

**4. Concurrency Safety**
- Race condition risks
- Mutex usage
- Channel coverage

**5. Error Handling**
- Ignored errors
- Error wrapping patterns

**6. Documentation**
- Exported function comments
- Documentation coverage %

**7. Test Coverage**
- Test file ratio

**8. Dependencies**
- Outdated packages

**9. Contract Bindings**
- Binding files present
- Bindings used in code

**10. Build Verification**
- Code compiles

**11. File Organization**
- Large files (>1MB)
- Deep nesting

**12. Git Status**
- Uncommitted changes

#### Output

- **Exit 0:** No issues found
- **Exit 1:** Issues found (review required)

Issues are categorized by severity:
- `[CRITICAL]` - Must fix immediately
- `[HIGH]` - Fix before commit
- `[MEDIUM]` - Fix soon
- `[LOW]` - Consider fixing
- `[INFO]` - Informational only

---

### `check-docs.sh` - Documentation Coverage

**Location:** `scripts/check-docs.sh`

**Purpose:** Ensure all code is properly documented.

#### Usage

```bash
./scripts/check-docs.sh
```

#### What It Checks

**1. Package Documentation**
- `doc.go` files in all packages

**2. Exported Functions**
- Comment on line before `func [A-Z]`

**3. Exported Types**
- Comment on line before `type [A-Z]`

**4. README Files**
- README.md in critical directories

**5. Project Documentation**
- SPEC.md
- CLAUDE.md
- README.md
- docs/DEVELOPMENT_SETUP.md

**6. Inline Comments**
- Comment density ratio

**7. API Documentation**
- API.md for HTTP endpoints

**8. Examples**
- Example code files

#### Output

- Coverage percentage
- List of undocumented items
- **Exit 0:** >80% coverage
- **Exit 1:** <80% coverage

---

### `check-compliance.sh` - SPEC.md Compliance

**Location:** `scripts/check-compliance.sh`

**Purpose:** Verify code adheres to all SPEC.md requirements.

#### Usage

```bash
./scripts/check-compliance.sh
```

#### What It Validates

**MUST DO Requirements ✅**

1. Use Arbitrum sequencer feed
2. Channel-based communication
3. Official contract ABIs
4. Generated bindings with abigen
5. Validate all parsed data
6. Thread-safe structures
7. Comprehensive metrics
8. Container-based development

**MUST NOT DO Requirements ❌**

1. HTTP RPC in sequencer
2. Manual ABI JSON files
3. Hardcoded function selectors
4. Zero addresses/amounts propagation
5. Blocking operations in hot paths
6. Unprotected shared state
7. Silent error failures

**Architecture Requirements 🏗️**

- Channel-based concurrency
- Sequencer isolation
- Pool cache with RWMutex

**Foundry Integration 🔨**

- foundry.toml present
- Correct Solidity version

**Development Scripts 🛠️**

- All required scripts present and executable

#### Output

- **Exit 0:** Fully compliant or minor issues (<5)
- **Exit 1:** Significant issues (>5)

Violations are categorized:
- `[CRITICAL]` - Core requirement violated
- `[HIGH]` - Important requirement violated
- `[MEDIUM]` - Recommended practice violated
- `[LOW]` - Minor issue

---

## Contract Scripts

### `generate-bindings.sh` - Legacy Binding Generator

**Location:** `scripts/generate-bindings.sh`

**Status:** Legacy script (use `dev.sh bindings` instead)

**Purpose:** Generate Go bindings from manually created ABI files.

#### Usage

```bash
./scripts/generate-bindings.sh
```

---

### `generate-bindings-in-container.sh` - Container Binding Generator

**Location:** `scripts/generate-bindings-in-container.sh`

**Purpose:** Generate Go bindings from Foundry artifacts inside Go container.

**Called by:** `./scripts/dev.sh bindings`

#### Usage

```bash
# From host (preferred)
./scripts/dev.sh bindings

# Manually inside Go container
./scripts/generate-bindings-in-container.sh
```

---

### `extract-official-abis.sh` - ABI Extraction

**Location:** `scripts/extract-official-abis.sh`

**Purpose:** Extract ABIs directly from official contracts using `forge inspect`.

#### Usage

```bash
./scripts/extract-official-abis.sh
```

Extracts:
- `bindings/uniswap_v2/IUniswapV2Pair_abi.json`
- `bindings/uniswap_v3/ISwapRouter_abi.json`

---

### `generate-bindings-from-official-abis.sh` - Official Binding Generator

**Location:** `scripts/generate-bindings-from-official-abis.sh`

**Purpose:** Generate bindings from extracted official ABIs.

#### Usage

```bash
# Extract ABIs first
./scripts/extract-official-abis.sh

# Generate bindings
./scripts/generate-bindings-from-official-abis.sh
```

---

## Utility Scripts

### `dev-up.sh` - Start Dev Environment

**Location:** `scripts/dev-up.sh`

**Purpose:** Start development containers (legacy - use `dev.sh up` instead).

#### Usage

```bash
./scripts/dev-up.sh
```

Starts:
- mev-go-dev
- mev-python-dev
- mev-foundry

---

### `dev-down.sh` - Stop Dev Environment

**Location:** `scripts/dev-down.sh`

**Purpose:** Stop development containers (legacy - use `dev.sh down` instead).

#### Usage

```bash
./scripts/dev-down.sh
```

---

## Quick Reference

### Daily Development

```bash
# Start working
./scripts/dev.sh up

# Build and test
./scripts/dev.sh build
./scripts/dev.sh test unit

# Before commit
./scripts/dev.sh test all
./scripts/dev.sh check-compliance
```

### Before Push

```bash
# Full validation
./scripts/dev.sh test all
./scripts/dev.sh test race
./scripts/dev.sh audit
./scripts/dev.sh check-compliance
./scripts/dev.sh check-docs
```

### Contract Development

```bash
# Build contracts
./scripts/dev.sh forge-build

# Generate bindings
./scripts/dev.sh bindings

# Test contracts
./scripts/dev.sh forge-test
```

### Troubleshooting

```bash
# View container logs
./scripts/dev.sh logs go-dev

# Restart containers
./scripts/dev.sh restart

# Clean and rebuild
./scripts/dev.sh reset
./scripts/dev.sh up
./scripts/dev.sh build
```

## Script Dependencies

```
dev.sh
├── test.sh                               # Testing suite
├── audit.sh                              # Code audit
├── check-docs.sh                         # Doc coverage
├── check-compliance.sh                   # SPEC compliance
└── generate-bindings-in-container.sh     # Binding generation

test.sh
└── (runs in mev-go-dev container)

audit.sh
└── (runs in mev-go-dev container for go vet)

generate-bindings-in-container.sh
└── (runs in mev-go-dev container)
    └── extract-official-abis.sh (optional)
```

## Environment Variables

Scripts respect these environment variables:

```bash
# Override container names
GO_CONTAINER=mev-go-dev
FOUNDRY_CONTAINER=mev-foundry
PYTHON_CONTAINER=mev-python-dev

# Test verbosity
TEST_VERBOSE=true

# Coverage threshold
COVERAGE_THRESHOLD=70
```

## Exit Codes

All scripts use consistent exit codes:

- **0:** Success (all checks passed)
- **1:** Failure (tests failed, violations found, etc.)
- **127:** Command not found
- **255:** Container error

## Logging

Scripts use consistent logging format:

- `ℹ` - Info message (blue)
- `✓` - Success (green)
- `⚠` - Warning (yellow)
- `✗` - Error (red)

## See Also

- [SPEC.md](../SPEC.md) - Technical specification
- [DEVELOPMENT_SETUP.md](DEVELOPMENT_SETUP.md) - Setup guide
- [AUDIT_AND_TESTING.md](AUDIT_AND_TESTING.md) - Testing guide
- [CLAUDE.md](../CLAUDE.md) - Development guidelines