forge-guard 0.1.2

# 🔒 Forge Guard

> **The most comprehensive pre-deployment smart contract auditing framework for Foundry.**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/Rust-1.85%2B-orange)](https://www.rust-lang.org)
[![Foundry](https://img.shields.io/badge/Foundry-compatible-blue)](https://book.getfoundry.sh/)
[![CI](https://github.com/codetibo/forge-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/codetibo/forge-guard/actions/workflows/ci.yml)
[![Nightly Audit](https://github.com/codetibo/forge-guard/actions/workflows/nightly-audit.yml/badge.svg)](https://github.com/codetibo/forge-guard/actions/workflows/nightly-audit.yml)
[![Dependabot](https://img.shields.io/badge/dependabot-enabled-025E8C?logo=dependabot)](https://github.com/codetibo/forge-guard/blob/main/.github/dependabot.yml)
[![Changelog](https://img.shields.io/badge/changelog-v0.1.0-blue?logo=github)](CHANGELOG.md)

---

## 📋 Table of Contents

- [Overview](#overview)
- [Key Features](#key-features)
- [Milestone Summary](#milestone-summary)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [All Commands](#all-commands)
- [Usage Examples](#detailed-usage-examples)
- [Configuration](#configuration)
- [Architecture](#architecture)
- [Security Checks](#security-checks)
- [Plugin Development](#plugin-development)
- [CI/CD Integration](#cicd-integration)
- [Performance](#performance)
- [Development](#development)
- [Supported Chains](#supported-chains)
- [Changelog](CHANGELOG.md)
- [Contributing](#contributing)
- [License](#license)
- [Roadmap](#roadmap)

---

## Overview

**Forge Guard** transforms security auditing from an optional step into a mandatory pre-deployment process. It blocks unsafe deployments by default while providing detailed vulnerability reports, exploit path analysis, and comprehensive security scoring.

Built with Rust for maximum performance, `forge-guard` integrates directly into your Foundry workflow as a drop-in CLI tool.

### Key Features

- 🔍 **50+ Vulnerability Checks** — Reentrancy, access control, delegatecall, flash loans, MEV, oracles, signatures, and more
- 🛡️ **Deployment Guard** — Blocks unsafe deployments by default; `--force` bypass available with warnings
- ✅ **On-Chain Verification** — Auto-verify contracts on Etherscan, Basescan, Arbiscan, and 14 more explorers
- 📡 **Bytecode Matching** — Compare local vs on-chain bytecode via RPC `eth_getCode` with metadata hash stripping
- 🔐 **MEV Analysis** — Detect sandwich, flash loan, oracle, and value extraction attack vectors during simulation
- 🤖 **AI-Powered Auditing** — OpenAI GPT-5, Anthropic Claude 5, and Ollama integration with consensus engine
- ⛓️ **Multi-Chain** — 17 supported EVM chains with auto-detected explorer URLs
- 🔌 **Plugin Architecture** — Extensible design for custom security rules; built-in + external (IPC subprocess) plugins
- 📊 **Rich Reports** — Terminal, JSON, and Markdown output with detailed findings, scores, and remediation
- 💥 **Exploit Engine** — Generates attack vectors and proof-of-concept exploit paths
- 🩺 **Project Doctor** — Comprehensive health analysis: Foundry version, Solc version, project structure, dependencies, RPC, compiler settings
- 🔎 **Dependency Scanner** — 30+ known vulnerability entries covering OpenZeppelin, Solmate, Solady, Chainlink, Wormhole, LayerZero, forge-std, PRBMath, solc, and more
- ⚡ **High Performance** — Parallel execution via Rayon, filesystem caching, incremental SHA-256 content-hash analysis (unchanged files skipped on re-runs)
- ⚡ **Quick Mode** — `forge audit --quick` skips parser-heavy checks, ~5x faster for rapid feedback
- 📋 **Executive Summary** — `forge audit --summary` shows concise PASS/FAIL verdict with action items
- 🏗️ **CI/CD Ready** — Generate pipeline configs for GitHub Actions, GitLab CI, Bitbucket Pipelines, Azure DevOps

---

## Milestone Summary

All 13 development milestones are complete. Here's what each delivered:

| # | Milestone | Key Deliverables |
|---|-----------|------------------|
| 🏗️ | **M1 — Core Architecture** | Cargo project, error handling, config system, module structure |
| 🎮 | **M2 — CLI Framework** | 18 subcommands via clap, global flags (`--json`, `--strict`, `--offline`, etc.) |
| 🔒 | **M3 — Security Engine** | 50+ vulnerability checks across 5 severity levels, 11-category scoring system |
| 🔌 | **M4 — Plugin Architecture** | Plugin trait, built-in + IPC subprocess plugins, lifecycle management |
| ⛓️ | **M5 — Multi-Chain** | 17 EVM chains, alias resolution, chain registry with RPC testing |
| 📊 | **M6 — Report Engine** | Terminal (color-coded), JSON, and Markdown reports with findings & scores |
| 🛡️ | **M7 — Deployment Guard** | Pre-deployment check pipeline, `deploy-safe` (non-bypassable), MEV detection |
| 💥 | **M8 — Exploit Engine** | Attack vector generation from findings, storage collision analysis |
| ✅ | **M9 — Contract Verification** | 17-chain explorer registry, `forge verify-contract`, RPC bytecode match, auto-verify |
| 🔧 | **M10 — Gas/Deps/Fuzz/CI** | Gas analysis, 30-entry vulnerability DB, fuzzing adapter, 4-platform CI templates |
| 🤖 | **M11 — AI Auditing** | OpenAI, Claude, Ollama providers, consensus engine, structured Solidity prompts |
| 🧪 | **M12 — Testing & Docs** | 200+ tests, comprehensive README, CONTRIBUTING.md, CI workflows |
| ⚡ | **M13 — Post-MVP Polish** | Quick mode (~5x faster), executive summary, incremental file analysis, `--summary` flag |

Detailed breakdown: [milestone-based-roadmap.md](milestone-based-roadmap.md)

---

## Installation

### Prerequisites

- **Rust** 1.85+ — [Install](https://www.rust-lang.org/tools/install)
- **Foundry** — [Install](https://book.getfoundry.sh/getting-started/installation)

### Option 1: Install via Cargo

```bash
cargo install forge-guard
```

### Option 2: Build from Source

```bash
git clone https://github.com/codetibo/forge-guard.git
cd forge-guard
cargo build --release
cp target/release/forge-guard ~/.foundry/bin/
```

### Option 3: Add to PATH

```bash
# Add to your .bashrc or .zshrc:
export PATH="$HOME/.foundry/bin:$PATH"
```

### Verify Installation

```bash
forge audit --version
forge audit --help
```

---

## Quick Start

Navigate to a Foundry project and run:

```bash
cd my-foundry-project

# Run a comprehensive security audit
forge audit

# Audit with strict mode (fail on any finding)
forge audit --strict

# Full audit including exploit paths and gas analysis
forge audit --full

# Check deployment readiness
forge audit --production

# Generate Markdown report
forge audit --markdown --report
```

### Example Output

```
═══════════════════════════════════════════════
           FORGE GUARD — SECURITY REPORT       
═══════════════════════════════════════════════

📋 Project:  .
⛓️  Chain:    ethereum
🕐 Duration:  0.00s
📁 Files:     1

── Findings ──
  🛑 Critical:  0
  🔴 High:     0
  🟡 Medium:   0
  🔵 Low:      0
  ⚪ Info:     0

── Scores ──
  🔐 Access Control:       100/100
  🛡️  Security:            100/100
  🎯 Fuzzing:             100/100
  ⛽ Gas:                  100/100
  🏗️  Architecture:        100/100
  ⬆️  Upgradeability:     100/100

Overall Score: 100
Risk Level: MINIMAL
Production Ready: ✅ YES
Deployment: ✅ APPROVED
```

---

## All Commands

| Command | Description | Example |
|---------|-------------|---------|
| `forge audit` | Run security audit with 50+ checks | `forge audit --full --chain base` |
| `forge audit --quick` | Quick audit (skips parser-heavy checks) | `forge audit --quick` |
| `forge audit --summary` | Executive summary report | `forge audit --summary` |
| `forge deploy` | Deploy with security guard | `forge deploy --force` |
| `forge deploy-safe` | Deploy with mandatory security pass | `forge deploy-safe Counter` |
| `forge fuzz` | Run fuzzing campaigns | `forge fuzz --runs 50000` |
| `forge invariant` | Run invariant tests | `forge invariant --runs 2000` |
| `forge simulate` | Deployment simulation | `forge simulate --blocks 200` |
| `forge gas` | Gas usage analysis | `forge gas --all` |
| `forge report` | Generate audit reports | `forge report --format markdown` |
| `forge verify` | Verify contract deployments | `forge verify --all` |
| `forge doctor` | Project health analysis | `forge doctor --fix` |
| `forge watch` | Watch for changes and re-audit | `forge watch --dirs src` |
| `forge ci` | Generate CI/CD configs | `forge ci --platform github` |
| `forge benchmark` | Performance benchmarks | `forge benchmark --iterations 50` |
| `forge scan` | Dependency vulnerability scan | `forge scan --update` |
| `forge upgrade-check` | Upgrade path analysis | `forge upgrade-check --all` |
| `forge plugins` | Manage plugins | `forge plugins list` |
| `forge chain` | Chain configuration | `forge chain list` |
| `forge security` | Security configuration | `forge security list` |

### Common Flags

```bash
--chain <NAME>     # Target chain (default: ethereum)
--json             # JSON output
--markdown         # Markdown output
--strict           # Fail on any MEDIUM+ finding
--offline          # Skip RPC calls
--production       # Production mode (extra checks)
--report           # Generate report files
--project <PATH>   # Project root path (default: .)
```

---

## Detailed Usage Examples

### Security Audit

```bash
# Standard audit
forge audit

# Full audit with everything
forge audit --full

# Cross-chain audit
forge audit --chain arbitrum
forge audit --chain base --chain polygon
forge audit --all-chains

# Output formats
forge audit --json
forge audit --markdown
forge audit --json --report   # Save to file

# Analysis scope
forge audit --strict           # Fail on any MEDIUM+ finding
forge audit --production       # Production readiness check
forge audit --offline          # Skip network calls
forge audit --exploit          # Include exploit path generation
forge audit --gas              # Include gas analysis
```

### Deployment Guard

```bash
# Safe deploy (blocked by issues)
forge deploy

# Deploy with bypass (warnings still shown)
forge deploy --force

# Deploy specific contract
forge deploy MyContract

# Mandatory security pass (no bypass)
forge deploy-safe MyContract

# Create2 deployment
forge deploy --salt 0xabc...

# Deploy with auto-verification
forge deploy MyContract --verify --api-key YOUR_ETHERSCAN_KEY
```

### Contract Verification

```bash
# Verify a single contract
forge verify --address 0x... --name MyContract

# Bulk verify all deployments from forge script
forge verify --all

# Verify on a specific chain
forge verify --address 0x... --name MyContract --chain base

# Explorer and bytecode match are attempted automatically
```

### Quick Mode & Executive Summary

```bash
# Quick audit — skip parser-heavy checks for ~5x faster results
forge audit --quick

# Show executive summary (concise PASS/FAIL verdict with action items)
forge audit --summary

# Combine both for fastest feedback loop
forge audit --quick --summary

# Still get the full report with --report
forge audit --quick --report
```

### AI-Powered Auditing

```bash
# Run audit with AI (uses OPENAI_API_KEY env var)
forge audit --ai

# Use Claude instead
forge audit --ai --ai-provider claude --ai-model claude-5-sonnet-20260701

# Full AI audit (security + gas + logic auditors)
forge audit --ai --ai-full

# Use local Ollama
forge audit --ai --ai-provider ollama --ai-model llama3
```

### Deployment Simulation

```bash
# Run deployment simulation
forge simulate

# With MEV analysis
forge simulate --mev

# Custom block range and deployer
forge simulate --blocks 200 --deployer 0x...
```

### Dependency Scanning

```bash
# Scan project dependencies
forge scan

# Deep scan (include indirect dependencies)
forge scan --depth 2

# Update vulnerability database
forge scan --update

# JSON output
forge scan --json

# Fail fast on critical vulnerabilities
forge scan --fail-fast
```

### Project Health

```bash
# Full health check
forge doctor

# Verbose output
forge doctor --verbose

# Auto-fix issues
forge doctor --fix

# Check specific category
forge doctor --check dependencies
```

### Plugin Management

```bash
# List installed plugins
forge plugins list

# Create a new plugin scaffold
forge plugins new my-custom-check

# Install from source
forge plugins install my-check https://github.com/user/my-check.git

# Enable/disable
forge plugins enable my-custom-check
forge plugins disable my-custom-check

# Remove
forge plugins remove my-custom-check
```

### CI/CD Generation

```bash
# GitHub Actions
forge ci --platform github

# GitLab CI
forge ci --platform gitlab

# With deployment pipeline
forge ci --platform github --include-deploy

# Custom output directory
forge ci --output .github/workflows

# Overwrite existing configs
forge ci --overwrite
```

---

## Configuration

Forge Guard reads configuration from `forge-guard.toml` in the project root. All fields are optional.

### Minimal Configuration

```toml
# forge-guard.toml
src_dirs = ["src", "contracts"]
```

### Full Configuration Reference

```toml
# ── Source Settings ──
src_dirs = ["src", "contracts"]           # Source directories to scan
exclude = ["test", "mock", "interfaces"]  # Exclusion patterns

# ── Chain ──
chain = "ethereum"                        # Default target chain

# ── Security Engine ──
[security]
enable_high = true                        # Enable HIGH severity checks
enable_medium = true                      # Enable MEDIUM severity checks
enable_low = true                         # Enable LOW severity checks
enable_info = false                       # Enable INFORMATIONAL checks
exploit_analysis = true                   # Enable exploit path analysis
gas_analysis = false                      # Enable gas analysis
max_findings_per_check = 50               # Max findings per check type

# ── Deployment Guard ──
[deployment]
min_score = 70                            # Minimum score to deploy (0-100)
block_on_critical = true                  # Block on critical findings
block_on_high = true                      # Block on high findings
block_on_medium = false                   # Block on medium findings
require_fuzzing = true                    # Require fuzzing to pass
require_invariants = true                 # Require invariants to pass
simulate_deployment = true                # Run deployment simulation
require_verification = false              # Require on-chain verification
auto_verify = false                       # Auto-verify after deployment
explorer_api_key = null                   # Explorer API key (reads env var when null)

# ── Report Settings ──
[report]
include_snippets = true                   # Include code snippets
include_exploit_paths = true              # Include exploit demonstrations
include_recommendations = true            # Include fix recommendations
output_dir = "reports"                    # Report output directory

# ── Caching ──
[cache]
enabled = false                           # Enable caching (disable for CI)
directory = ".forge-guard-cache"          # Cache directory
max_size_mb = 500                         # Maximum cache size
ttl_seconds = 3600                        # Cache TTL (1 hour)

# ── Plugin Configuration ──
[plugins]
directories = [".forge-guard/plugins"]    # Plugin search paths
disabled = ["forge-guard-example"]        # Disable specific plugins
allow_external = false                    # Allow external plugin loading

# ── AI Auditors ──
[ai]
provider = "openai"                       # AI provider: openai, claude, ollama
model = "gpt-5"                            # Model identifier
temperature = 0.1                         # Sampling temperature (0.0-1.0)
max_tokens = 4000                         # Max tokens per response
min_confidence = 0.5                      # Minimum confidence (0.0-1.0)
full_audit = false                        # Run all auditors (security + gas + logic)
```

### Command-Line Overrides

CLI flags override config file values:

```bash
forge audit --strict         # Overrides security config
forge audit --chain base     # Overrides default chain
forge audit --offline        # Skips RPC
```

---

## Architecture

```
                    ┌─────────────┐
                    │   CLI Layer  │  (clap argument parsing)
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
       ┌──────────┐ ┌──────────┐ ┌──────────┐
       │  Audit   │ │  Deploy  │ │   CI     │  ... 18 commands
       └────┬─────┘ └────┬─────┘ └────┬─────┘
            │             │            │
            ▼             ▼            ▼
       ┌─────────────────────────────────────┐
       │           Security Engine            │
       │  ┌──────┐ ┌──────┐ ┌─────────────┐  │
       │  │CEI   │ │Access│ │Delegatecall │  │ 50+ checks
       │  │Analysis│ │Control││             │  │
       │  └──────┘ └──────┘ └─────────────┘  │
       └────────────────┬────────────────────┘
                        │
              ┌─────────┴─────────┐
              ▼                   ▼
       ┌──────────────┐ ┌──────────────────┐
       │Plugin Registry│ │  Chain Registry   │
       │ Built-in/IPC  │ │  17 EVM Chains    │
       └──────────────┘ └──────────────────┘
                        │
              ┌─────────┴─────────┐
              ▼                   ▼
       ┌──────────────┐ ┌──────────────────┐
       │Deployment    │ │  Report Engine    │
       │Guard         │ │  JSON / Markdown  │
       └──────────────┘ └──────────────────┘
                        │
              ┌─────────┴─────────┐
              ▼                   ▼
       ┌──────────────┐ ┌──────────────────┐
       │  Exploit     │ │  Doctor / Scan   │
       │  Engine      │ │  Health Checks   │
       └──────────────┘ └──────────────────┘
```

### Module Breakdown

| Module | Purpose |
|--------|---------|
| `src/core/` | Types, config, error handling, audit results |
| `src/security/` | 50+ vulnerability checks + scoring engine |
| `src/plugins/` | Plugin trait, built-in + external (IPC) plugins |
| `src/chains/` | Chain registry with 17 EVM chains |
| `src/deployment/` | Deployment guard + on-chain contract verifier |
| `src/deployment/verifier/` | Block explorer registry, forge verify, RPC bytecode match |
| `src/reports/` | JSON and Markdown report generation |
| `src/exploit/` | Attack vector and exploit path generation |
| `src/dependencies/` | 30+ known vulnerability entries, online updates |
| `src/doctor/` | Project health analysis |
| `src/gas/` | Gas usage analysis and optimization suggestions |
| `src/fuzzing/` | Fuzzing adapter interface |
| `src/ci/` | CI/CD pipeline template generation |
| `src/benchmark/` | Performance benchmarking |
| `src/parser/` | Solidity source code parser |
| `src/ai/` | AI auditing: providers (OpenAI, Claude, Ollama), auditors, consensus engine |
| `src/ai/providers/` | OpenAI, Claude, Ollama HTTP client implementations |
| `src/ai/auditors/` | Security, Gas, Logic auditor agents with Solidity prompts |
| `src/ai/consensus/` | Cross-provider validation with confidence boosting |
| `src/utils/` | Caching, formatting utilities |

---

## Security Checks

### HIGH Severity (blocks deployment)

| ID | Check | Description |
|----|-------|-------------|
| FA-H-001 | Reentrancy | CEI violations, callback reentrancy, read-only reentrancy, self-call paths |
| FA-H-002 | Access Control | Missing modifiers, inline access checks, role-based access in initialize functions |
| FA-H-003 | Delegatecall | Unsafe delegatecall patterns |
| FA-H-004 | tx.origin | tx.origin for authentication |
| FA-H-005 | CREATE2 | CREATE2 address precomputation risks |
| FA-H-006 | DoS | Unbounded loops, denial of service |
| FA-H-007 | Storage Collision | Upgradeable contract storage gaps |
| FA-H-008 | Unsafe Assembly | Inline assembly blocks |
| FA-H-009 | Selfdestruct | selfdestruct usage |
| FA-H-010 | Proxy Vulnerabilities | Unsafe proxy patterns |
| FA-H-011 | Oracle Manipulation | Price oracle manipulation risks |
| FA-H-012 | Signature Vulnerabilities | Signature malleability, EIP-2098 issues |
| FA-H-013 | Replay Attacks | Cross-chain replay, missing nonces |
| FA-H-014 | ERC20 Issues | Approve race conditions |
| FA-H-015 | Bridge Vulnerabilities | Cross-chain bridge patterns |
| FA-H-016 | Flash Loan Issues | Flash loan attack surface |
| FA-H-017 | MEV Issues | Slippage, sandwich vulnerabilities |
| FA-H-018 | Cross-Chain Issues | Chain ID handling, message verification |
| FA-H-019 | Dependency Vulnerabilities | Known vulnerable dependencies |
| FA-H-020 | Unsafe Imports | HTTP/github imports |
| FA-H-021 | Unsafe Initializers | Missing initializer modifiers |
| FA-H-022 | Unsafe Upgrade Paths | UUPS/Transparent proxy paths |
| FA-H-023 | Clone Vulnerabilities | Minimal proxy clones |

### MEDIUM Severity

| ID | Check | Description |
|----|-------|-------------|
| FA-M-001 | Gas Problems | Inefficient patterns |
| FA-M-002 | Unsafe Casting | Unsafe type conversions |
| FA-M-003 | Timestamp Manipulation | block.timestamp in critical logic |
| FA-M-004 | Storage Inefficiencies | Unpacked storage variables |
| FA-M-005 | Unsafe Events | Sensitive data in events |
| FA-M-006 | Poor Visibility | Public mappings |
| FA-M-007 | Bad Modifiers | Modifiers making external calls |
| FA-M-008 | Unsafe Math | Unchecked arithmetic |
| FA-M-009 | Poor Access Patterns | Storage vs memory |

### LOW & INFORMATIONAL

- Naming conventions
- Code duplication
- Optimization suggestions
- Style issues
- Missing documentation
- Line length

---

## Plugin Development

### Built-in Plugin

Create a built-in plugin by implementing the `Plugin` trait:

```rust
use forge_guard::plugins::{Plugin, PluginContext, PluginResult};

pub struct MyCustomCheck;

impl Plugin for MyCustomCheck {
    fn name(&self) -> &'static str { "my-custom-check" }
    fn version(&self) -> &'static str { "0.1.0" }
    fn description(&self) -> &'static str { "My custom security check" }

    fn execute(&self, ctx: &PluginContext) -> PluginResult {
        // Your analysis logic here
        // ctx.source_files contains the Solidity files to analyze
        // ctx.config has the project configuration
        Ok(Vec::new()) // Return findings
    }
}
```

### External Plugin (IPC Subprocess)

Plugins can also be external binaries communicating via JSON IPC:

```bash
# Create a plugin scaffold
forge plugins new my-external-check
cd .forge-guard/plugins/my-external-check
cargo build --release
forge plugins list
```

The protocol:
- **stdin**: JSON `PluginIpcInput` with context
- **stdout**: JSON `PluginIpcOutput` with findings
- **stderr**: Diagnostic logs

---

## CI/CD Integration

### GitHub Actions (auto-generated)

```yaml
# Run: forge ci --platform github
name: Forge Guard Security Check
on: [push, pull_request]
jobs:
  security-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive
      - uses: foundry-rs/foundry-toolchain@v1
        with:
          version: nightly
      - name: Install Forge Guard
        run: cargo install forge-guard
      - name: Security Audit
        run: forge audit --strict
      - name: Scan Dependencies
        run: forge scan --depth 1
      - name: Generate Report
        run: forge audit --report --markdown
```

### With Deployment Protection

```yaml
name: Deploy
on:
  push:
    branches: [main]
jobs:
  security-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: foundry-rs/foundry-toolchain@v1
      - name: Security check
        run: forge audit --strict --production
      - name: Safe deploy
        run: forge deploy-safe
        env:
          ETH_RPC_URL: ${{ secrets.ETH_RPC_URL }}
          PRIVATE_KEY: ${{ secrets.DEPLOYER_PRIVATE_KEY }}
```

---

## Performance

- **Parallel execution** via Rayon — all file analysis runs in parallel across CPU cores
- **Filesystem caching** — analysis results cached with TTL; only changed files re-analyzed
- **Memory-efficient** — streaming reads for large codebases
- **Incremental** — re-audits only process modified files
- **Benchmark mode** — measure and compare performance across versions

```bash
# Run benchmarks
forge benchmark --iterations 50

# Benchmark specific module
forge benchmark --module source_discovery

# Compare with baseline
forge benchmark --compare baseline.json
```

---

## Development

### Building

```bash
git clone https://github.com/codetibo/forge-guard.git
cd forge-guard
cargo build
cargo build --release    # Production build
```

### Testing

```bash
# Run all tests (200+)
cargo test

# Run specific test suites
cargo test --lib              # Unit tests
cargo test --test mod         # Integration tests
cargo test --test integration # Quick mode & incremental analysis tests
cargo test --lib dependencies # Dependency scanner tests
cargo test --lib plugins      # Plugin tests

# Run with output
cargo test -- --nocapture
```

### Linting & Formatting

```bash
# Check formatting
cargo fmt --check

# Apply formatting
cargo fmt

# Lint
cargo clippy -- -D warnings
```

### Test Coverage

| Module | Tests | Status |
|--------|-------|--------|
| AI providers (OpenAI, Claude, Ollama) | ✅ 11 | in-module tests |
| AI auditors (prompts, parsing, chunking) | ✅ 12 | in-module tests |
| AI consensus (dedup, boost, filtering) | ✅ 9 | in-module tests |
| Contract verifier (explorer URLs, bytecode) | ✅ 11 | in-module tests |
| Core types/config | ✅ 8 | integration_tests |
| Security engine | ✅ 6 | security_tests |
| Plugin architecture | ✅ 25 | plugin_tests |
| Dependency scanner | ✅ 14 | in-module tests |
| Parser | ✅ 39 | in-module tests |
| Chains | ✅ 8 | in-module tests |
| Deployment | ✅ 6 | in-module tests |
| Reports | ✅ 3 | in-module tests |
| Exploit engine | ✅ 2 | in-module tests |
| Utils | ✅ 6 | in-module tests |
| Gas analysis | ✅ 3 | in-module tests |
| CI generator | ✅ 5 | in-module tests |
| Doctor | ✅ 4 | in-module tests |

---

## Supported Chains

| Chain | Chain ID | Currency | Status |
|-------|----------|----------|--------|
| Ethereum | 1 | ETH | ✅ |
| Base | 8453 | ETH | ✅ |
| Arbitrum | 42161 | ETH | ✅ |
| Optimism | 10 | ETH | ✅ |
| Polygon | 137 | MATIC | ✅ |
| BNB Chain | 56 | BNB | ✅ |
| Avalanche | 43114 | AVAX | ✅ |
| Scroll | 534352 | ETH | ✅ |
| Linea | 59144 | ETH | ✅ |
| Unichain | 130 | ETH | ✅ |
| ZKSync | 324 | ETH | ✅ |
| HyperEVM | 999 | HYPE | ✅ |
| Monad | 10143 | MON | ✅ |
| Sonic | 146 | S | ✅ |
| Blast | 81457 | ETH | ✅ |
| Mantle | 5000 | MNT | ✅ |
| Robinhood | 31753 | ETH | ✅ |

### Future Support
Solana · Tron · Sui · Aptos

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

Key points:
- Run `cargo test && cargo fmt && cargo clippy` before submitting PRs
- Add tests for new functionality
- Document public APIs
- Follow Rust standard conventions

---

## License

MIT — see [LICENSE](LICENSE) for details.

---

## Roadmap

See [milestone-based-roadmap.md](milestone-based-roadmap.md) for the complete development roadmap.

| Milestone | Status |
|-----------|--------|
| M1: Core Architecture | ✅ Complete |
| M2: CLI Framework | ✅ Complete |
| M3: Security Engine | ✅ Complete |
| M4: Plugin Architecture | ✅ Complete |
| M5: Multi-Chain Support | ✅ Complete |
| M6: Report Engine | ✅ Complete |
| M7: Deployment Guard | ✅ Complete |
| M8: Exploit Engine | ✅ Complete |
| M9: Contract Verification | ✅ Complete |
| M10: Gas/Deps/Fuzz/CI/Bench | ✅ Complete |
| M11: AI-Powered Auditing | ✅ Complete |
| M12: Testing & Documentation | ✅ Complete |
| M13: Post-MVP Polish | ✅ Complete |