forge-guard 0.2.1

# Contributing to Forge Guard

## Welcome

We're thrilled you're interested in contributing to **Forge Guard** — the most comprehensive pre-deployment smart contract auditing framework for Foundry.

This project transforms security auditing from an optional step into a mandatory pre-deployment process. Every contribution helps make the ecosystem safer.

---

## Quick Start

```bash
git clone https://github.com/codetibo/forge-guard.git
cd forge-guard
cargo build
cargo test
cargo clippy -- -D warnings
```

---

## Development Workflow

### 1. Find or Create an Issue

Check [existing issues](https://github.com/codetibo/forge-guard/issues) or create a new one describing your proposed change.

### 2. Fork & Branch

```bash
git checkout -b feat/my-feature
```

Branch naming:
- `feat/` — New features
- `fix/` — Bug fixes
- `docs/` — Documentation
- `test/` — Test additions
- `refactor/` — Code refactoring

### 3. Implement

#### Code Style

- Run `cargo fmt` before committing
- Run `cargo clippy -- -D warnings` — zero warnings required
- Follow Rust naming conventions:
  - `snake_case` for functions, variables, modules
  - `CamelCase` for types, traits, enums
  - `SCREAMING_CASE` for constants
- Write doc comments (`///`) for all public items
- Keep functions focused and small (< 50 lines preferred)

#### Adding Tests

Every module should have a `#[cfg(test)] mod tests` block with:

- **Unit tests** — Test individual functions and methods
- **Edge cases** — Empty inputs, error conditions, boundary values
- **Round-trip tests** — Serialize/deserialize when applicable

```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_basic_functionality() {
        // Arrange
        let input = "test";
        // Act
        let result = process(input);
        // Assert
        assert_eq!(result, expected);
    }

    #[test]
    fn test_edge_cases() {
        assert!(process("").is_err());
        assert!(process(&"a".repeat(1000)).is_ok());
    }
}
```

#### Tests Checklist

Before submitting:

- [ ] All tests pass: `cargo test`
- [ ] No clippy warnings: `cargo clippy -- -D warnings`
- [ ] Proper formatting: `cargo fmt --check`
- [ ] New tests added for new functionality
- [ ] Existing tests updated if behavior changed
- [ ] Integration tests updated if CLI behavior changed

### 4. Submit a PR

1. Push your branch
2. Open a PR against `main`
3. Reference the issue number
4. Describe your changes
5. Wait for CI to pass

---

## Adding Security Checks

1. Add the check metadata to `src/security/checks.rs`:
   ```rust
   pub static MY_CHECK: SecurityCheckMeta = SecurityCheckMeta {
       id: "FA-H-024",
       name: "My Check",
       severity: "high",
       // ...
   };
   ```

2. Register in `checks::ALL_CHECKS` list

3. Implement the check logic in `src/security/engine.rs`:
   ```rust
   fn check_my_check(&self, file: &str, lines: &[&str], content: &str) -> Vec<Finding> {
       // Your detection logic
   }
   ```

4. Add to the match in `execute_check()`

5. Add tests in `tests/security_tests.rs`

---

## Adding Chain Support

1. Add a new variant to `ChainId` in `src/core/types.rs`:
   ```rust
   pub enum ChainId {
       // ... existing chains
       MyNewChain,
   }
   ```

2. Add chain info in `src/chains/mod.rs`:
   ```rust
   ChainInfo {
       name: "MyNewChain".into(),
       chain_id: 12345,
       currency: "TOKEN".into(),
       explorer_url: "https://explorer.mynewchain.io".into(),
       rpc_urls: vec!["https://rpc.mynewchain.io".into()],
       is_evm: true,
       supported: true,
   }
   ```

3. Update `from_name()` and `name()` in `ChainId`

4. Add tests for the new chain

---

## Adding Plugins

### Built-in Plugin

```rust
pub struct MyPlugin;

impl Plugin for MyPlugin {
    fn name(&self) -> &'static str { "my-plugin" }
    fn version(&self) -> &'static str { "0.1.0" }
    fn description(&self) -> &'static str { "Description" }

    fn execute(&self, ctx: &PluginContext) -> PluginResult {
        // Analyze ctx.source_files
        Ok(findings)
    }
}

// Register in register_default_plugins()
registry.register_builtin(Box::new(MyPlugin));
```

### External Plugin (IPC)

External plugins are standalone binaries communicating via JSON:

```
stdin  ← PluginIpcInput  (context + config)
stdout → PluginIpcOutput (findings + stats)
stderr → Diagnostic logs
```

Create a scaffold:
```bash
forge-guard plugins new my-external-plugin
```

---

## Project Structure

```
forge-guard/
├── src/
│   ├── main.rs              # Binary entry point
│   ├── lib.rs               # Library root
│   ├── cli/                 # CLI argument parsing & dispatch
│   ├── core/                # Types, config, error handling
│   ├── security/            # 50+ vulnerability checks
│   ├── plugins/             # Plugin architecture
│   ├── chains/              # Multi-chain support
│   ├── deployment/          # Deployment guard
│   ├── reports/             # JSON & Markdown reports
│   ├── exploit/             # Exploit path analysis
│   ├── dependencies/        # Vulnerability database
│   ├── doctor/              # Project health analysis
│   ├── gas/                 # Gas analysis
│   ├── fuzzing/             # Fuzzing adapter
│   ├── ci/                  # CI/CD template generation
│   ├── benchmark/           # Performance benchmarking
│   ├── parser/              # Solidity parser
│   ├── ai/                  # AI extension points
│   └── utils/               # Utilities (cache, formatting)
├── tests/
│   ├── mod.rs               # Test module root
│   ├── integration_tests.rs # Core integration tests
│   ├── security_tests.rs    # Security check tests
│   └── plugin_tests.rs      # Plugin tests
├── test-contracts/          # Sample Solidity contracts
├── forge-guard.toml         # Tool configuration
└── Cargo.toml               # Rust dependencies
```

---

## Code of Conduct

Be respectful, inclusive, and constructive. We're building security tools for everyone.

- **Respectful** — Disagreement is fine, personal attacks are not
- **Inclusive** — Everyone is welcome regardless of background
- **Constructive** — Focus on solutions, not blame
- **Collaborative** — Help others learn and grow

---

## Getting Help

- Open an issue for bugs or feature requests
- Check the [README.md](README.md) for usage documentation
- Review [milestone-based-roadmap.md](milestone-based-roadmap.md) for the project plan

---

Thank you for contributing to safer smart contracts! 🛡️