# Contributing to Theseus

Thank you for your interest in contributing to Theseus! This document provides guidelines and instructions for contributing.

## Building

### Prerequisites

- Rust 1.75 or later
- SQLite (bundled via `rusqlite`, no external dependency)

### Build Commands

```bash
# Debug build
cargo build

# Release build (recommended for production)
cargo build --release

# Build with specific features
cargo build --release --features verbose-logging
```

The binary is output to:
- Debug: `target/debug/theseus`
- Release: `target/release/theseus`

## Testing

### Rust Unit Tests

```bash
# Run all tests
cargo test

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

# Run specific test
cargo test test_name
```

### Python E2E Tests

The E2E tests require a running server. They are located in `tests/` and `e2e/`.

```bash
# Run all E2E tests via the runner script
./e2e/run_all.sh

# Run a specific E2E test
python3 tests/e2e_test.py

# Run individual test modules
python3 e2e/test_projects.py
python3 e2e/test_nodes.py
python3 e2e/test_edges.py
python3 e2e/test_analysis.py
```

The test runner (`run_all.sh`) automatically:
1. Builds the debug binary if needed
2. Starts the server on port 3080
3. Waits for the server to be ready
4. Runs all test modules
5. Stops the server

### Test Coverage Areas

| Module | Coverage Status |
|--------|----------------|
| `src/routes/` | Covered (routes) |
| `src/agent/` | **Untested** |
| `src/main.rs` | **Untested** |

## Code Style

### Formatting

Theseus uses `rustfmt` for code formatting:

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

# Format all code
cargo fmt
```

### Linting

Clippy is used for linting:

```bash
# Run clippy with recommended lints
cargo clippy -- -D warnings
```

### Pre-commit Hook

Run formatting and linting before committing:

```bash
cargo fmt && cargo clippy -- -D warnings && cargo test
```

## PR Guidelines

### Before Submitting

1. **Test your changes** — Run `cargo test` and ensure all existing tests pass
2. **Format your code** — Run `cargo fmt` to ensure consistent formatting
3. **Address clippy warnings** — Run `cargo clippy -- -D warnings` and fix any issues
4. **Write tests** — Add tests for new functionality in appropriate test modules
5. **Update documentation** — Update `README.md`, `CHANGELOG.md`, and inline comments as needed

### PR Requirements

- **Scope** — Keep PRs focused. One feature or fix per PR is preferred.
- **Commits** — Use clear, concise commit messages describing the change
- **Changelog** — Add an entry under `[Unreleased]` in `CHANGELOG.md` for user-facing changes
- **Breaking changes** — Clearly document any breaking changes and bump the minor version

### PR Description Template

```markdown
## Summary
Brief description of the change.

## Motivation
Why is this change needed?

## Changes
- List of specific changes made

## Testing
How was this tested?

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Changelog updated
- [ ] `cargo fmt` applied
- [ ] `cargo clippy` passes
```

## Architecture Overview

For a detailed understanding of the codebase, see [docs/context/architecture.md](docs/context/architecture.md).

### Key Entry Points

| File | Role |
|------|------|
| `src/lib.rs` | Server entry point: AppState, serve(), middleware, DeepSeek client |
| `src/main.rs` | CLI entry point: clap derive, all CLI commands, HTTP client helpers |
| `src/db.rs` | Database layer: SQLite operations, row deserializers |
| `src/types.rs` | Shared types: Node, Edge, Credential, ApiResponse, enums |
| `src/routes/` | 15 route modules merged into the API router |
| `src/agent/` | AI agent subsystem: LLM client, agent loop, memory, tools |

### Module Dependency Direction

```
main → lib → routes → db → types
```

The CLI (`main.rs`) has zero direct DB access. All operations go through the REST API.

## Known Gaps (Help Wanted)

These issues are documented in the [project review](docs/review/summary.md) and represent high-impact, low-effort improvements:

1. **Add CI pipeline** — GitHub Actions with `cargo fmt --check && cargo clippy && cargo test`
2. **Add HTTP timeouts** — `.timeout(Duration::from_secs(60))` on all `reqwest::Client` instances
3. **Add graceful shutdown** — Signal handling for in-flight requests
4. **Add `PRAGMA busy_timeout`** — Prevents `SQLITE_BUSY` under concurrent access
5. **Extract lib.rs modules** — Split the 900-line `lib.rs` into `error.rs`, `config.rs`, `resolve.rs`
6. **Add agent subsystem tests** — The `src/agent/` module has zero test coverage
7. **Add retry/backoff logic** — Handle DeepSeek 429/502/503 errors with exponential backoff

## License

By contributing to Theseus, you agree that your contributions will be licensed under the MIT License.
