# Contributing to SocratiCode

Thank you for your interest in contributing to SocratiCode! This document explains the process for contributing and what to expect.

## Contributor License Agreement

By submitting a pull request, you agree to the [Contributor License Agreement (CLA)](CLA.md). This is necessary because SocratiCode is dual-licensed (AGPL-3.0 + commercial). The CLA allows us to offer commercial licenses that include community contributions.

## Getting Started

### Prerequisites

- Node.js 18+
- Docker (for integration and E2E tests)
- Git

### Setup

```bash
git clone https://github.com/giancarloerra/socraticode.git
cd socraticode
npm install
npm run build
```

### Running Tests

```bash
# Unit tests (no Docker needed)
npm run test:unit

# Integration tests (requires Docker)
npm run test:integration

# End-to-end tests (requires Docker)
npm run test:e2e

# All tests
npm test

# Type checking
npx tsc --noEmit
```

See the [Developer Guide](DEVELOPER.md) for architecture details, data flows, and how the test infrastructure works.

## How to Contribute

### Reporting Bugs

Use the [Bug Report](https://github.com/giancarloerra/socraticode/issues/new?template=bug_report.yml) issue template. Include:

- Steps to reproduce
- Expected vs actual behaviour
- Your environment (OS, Node.js version, embedding provider, MCP host)
- Log output if available (set `SOCRATICODE_LOG_LEVEL=debug`)

### Suggesting Features

Use the [Feature Request](https://github.com/giancarloerra/socraticode/issues/new?template=feature_request.yml) issue template. Explain the problem you're trying to solve and your proposed approach.

### Submitting Pull Requests

1. **Fork** the repository and create a branch from `main`
2. **Make your changes** — follow the existing code style and conventions
3. **Add tests** — new functionality needs test coverage; bug fixes should include a regression test
4. **Update documentation** — if your changes affect the public API, update README.md and/or DEVELOPER.md
5. **Verify** — run `npm run lint && npx tsc --noEmit && npm run test:unit`
6. **Open a PR** — fill out the pull request template

### Commit Message Convention

We use [Conventional Commits](https://www.conventionalcommits.org/) to auto-generate the changelog:

```
feat: add fuzzy search support
fix: resolve race condition in watcher
docs: update quickstart guide
refactor: simplify provider factory
test: add watcher edge-case tests
chore: update dependencies
```

Prefix with the type, then a short imperative description. Use `feat:` for new features, `fix:` for bug fixes, and `chore:` for maintenance that doesn't need a changelog entry.

### What Makes a Good PR

- **Focused** — one logical change per PR
- **Tested** — unit tests at minimum; integration tests for infrastructure changes
- **Documented** — JSDoc comments on public functions, README/DEVELOPER.md updates where needed
- **Clean history** — squash fixup commits before requesting review
- **Conventional commits** — use the format above so the changelog generates correctly

## Code Style

- **TypeScript** with strict mode enabled
- **ESM** (ES modules) — use `.js` extensions in imports
- **Functional style** — prefer pure functions, avoid classes where unnecessary
- **Structured logging** — use `logger.info/warn/error/debug` with context objects, not `console.log`
- **Error messages** — user-friendly, actionable, include troubleshooting hints
- **JSDoc** on all exported functions
- **SPDX license header** on all source files:
  ```typescript
  // SPDX-License-Identifier: AGPL-3.0-only
  // Copyright (C) 2026 Giancarlo Erra - Altaire Limited
  ```

## Project Structure

```
src/services/   — Core business logic (docker, indexer, embeddings, etc.)
src/tools/      — MCP tool handlers (one file per tool group)
src/config.ts   — Project ID and collection naming
src/constants.ts — All configurable constants
tests/unit/     — Unit tests (no Docker)
tests/integration/ — Integration tests (Docker required)
tests/e2e/      — End-to-end tests (Docker required)
```

See [DEVELOPER.md](DEVELOPER.md) for the full architecture overview.

## Review Process

- All PRs are reviewed by a maintainer
- [CodeRabbit](https://coderabbit.ai) automatically reviews every PR — address or resolve all comments before requesting human review
- CI must pass (tests + type checking)
- One approval required to merge
- Maintainers may request changes or suggest alternatives

## Questions?

- Open a [Discussion](https://github.com/giancarloerra/socraticode/discussions) for questions
- Check the [README](README.md) and [Developer Guide](DEVELOPER.md) for existing documentation

Thank you for helping make SocratiCode better!