# Contributing to clrd

First off, thanks for taking the time to contribute!

## Code of Conduct

This project and everyone participating in it is governed by our commitment to providing a welcoming and inclusive environment. Please be respectful and constructive in all interactions.

## How Can I Contribute?

### Reporting Bugs

Before creating bug reports, please check existing issues to avoid duplicates.

When creating a bug report, include:

- **Clear title** describing the issue
- **Steps to reproduce** the behavior
- **Expected behavior** vs actual behavior
- **Environment details** (OS, Rust version, Node version)
- **Code samples** if applicable

### Suggesting Features

Feature requests are welcome! Please:

- Check if the feature has already been requested
- Describe the use case and why it would be valuable
- Consider how it fits with the project's philosophy

### Pull Requests

1. **Fork** the repository
2. **Create a branch** for your feature (`git checkout -b feature/amazing-feature`)
3. **Make your changes**
4. **Write or update tests** as needed
5. **Run the test suite** (`cargo test`)
6. **Commit your changes** (`git commit -m 'Add amazing feature'`)
7. **Push to your branch** (`git push origin feature/amazing-feature`)
8. **Open a Pull Request**

## Development Setup

### Prerequisites

- Rust 1.75 or higher
- Node.js 18 or higher (for npm builds)

### Getting Started

```bash
# Clone your fork
git clone https://github.com/YOUR_USERNAME/clrd.git
cd clrd

# Build the project
cargo build

# Run tests
cargo test

# Run the CLI
cargo run -- scan --format pretty
```

### Building for npm

```bash
# Install Node dependencies
npm install

# Build native module
npm run build

# Test npm package
node bin/clrd.js scan
```

## Project Structure

```
src/
├── main.rs           # CLI binary entry point
├── lib.rs            # Library root + NAPI exports
├── cli/              # Command implementations
├── scanner/          # Dead code detection engine
├── mapper/           # AI context file generation
├── tui/              # Terminal UI
└── types/            # Core data structures
```

## Coding Guidelines

### Rust Style

- Follow standard Rust formatting (`cargo fmt`)
- Use `clippy` for linting (`cargo clippy`)
- Write doc comments for public APIs
- Use `anyhow::Result` for error handling in application code
- Use `thiserror` for library error types

### Commit Messages

- Use present tense ("Add feature" not "Added feature")
- Use imperative mood ("Move cursor to..." not "Moves cursor to...")
- Keep the first line under 72 characters
- Reference issues when applicable

Good examples:
```
Add confidence threshold flag to scan command
Fix false positive detection for barrel files
Improve parallel file walking performance
```

### Testing

- Write unit tests for new functionality
- Ensure existing tests pass
- Add integration tests for CLI commands when appropriate

```bash
# Run all tests
cargo test

# Run specific test
cargo test test_scanner_creation

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

## Areas We Need Help

- **Module Resolution** — Improving TypeScript-style path resolution
- **Framework Detection** — Better handling of React, Vue, Angular patterns
- **Performance** — Caching and incremental scanning
- **Documentation** — Examples, tutorials, and guides
- **Platform Testing** — Testing on different OS and architectures

## Questions?

Feel free to open an issue for any questions about contributing.

Thank you for helping make clrd better!
