# Contributing to CVC

Thanks for your interest in contributing to CVC (Cognitive Version Control).

---

## Development Setup

### Prerequisites

- **Bun 1.x** — [Install from bun.sh](https://bun.sh/)
- **Git 2.x+**
- **Node.js 18+** (optional, for compatibility testing)

### Getting Started

```bash
git clone https://github.com/your-org/cvc.git
cd cvc/cvc-node
bun install
bun run dev         # Run from source
```

### Verify Your Setup

```bash
bun run typecheck   # Must pass with zero errors
bun run lint        # Biome — must pass
bun test            # All tests green
```

---

## Architecture Overview

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full system design.

### Module Map

| Directory | Purpose |
|-----------|---------|
| `src/core/` | Database, delta compression, models, pageindex |
| `src/agent/` | Chat REPL, tool executor, LLM client, plugins, hooks |
| `src/adapters/` | LLM provider adapters (Anthropic, OpenAI, Gemini, etc.) |
| `src/operations/` | CVC operations engine + routing |
| `src/vcs/` | Git shadow branches + notes bridge |
| `src/cli.ts` | Commander.js CLI (26 commands) |
| `src/proxy.ts` | Hono-based HTTP cognitive proxy |
| `src/mcp-server.ts` | MCP (Model Context Protocol) server |

### Key Patterns

- **Lazy imports**: Heavy modules use `require()` to keep startup fast
- **Adapter pattern**: Each LLM provider implements a common interface in `src/adapters/`
- **Hook system**: 9 events, shell-script or JS hooks, exit-code semantics (0=proceed, 1=ask, 2=block)
- **Plugin discovery**: Auto-scans `.cvc/plugins/` and `~/.cvc/plugins/`

---

## Code Style

### TypeScript

- **Strict mode**: `tsconfig.json` has `strict: true`. No `any` without justification.
- **Module system**: ESM (`"type": "module"`). Use `.js` extensions in imports (Bun resolves `.ts`).
- **Path aliases**: `@cvc/*` → `src/*` (configured in tsconfig).

### Biome

We use [Biome](https://biomejs.dev/) for linting and formatting:

```bash
bun run lint           # Check
bunx biome check --fix src/  # Auto-fix
```

Key rules:
- No `var` — use `const` or `let`
- No explicit `any` without `biome-ignore` comment
- No assignments in expressions
- Prefer `===` over `==`

### Naming Conventions

| Element | Style | Example |
|---------|-------|---------|
| Files | kebab-case | `delta-engine.ts` |
| Classes | PascalCase | `DeltaEngine` |
| Functions | camelCase | `computeDelta()` |
| Constants | UPPER_SNAKE | `DEFAULT_ANCHOR_INTERVAL` |
| Interfaces | PascalCase | `CVCConfig` |
| Type aliases | PascalCase | `HookEvent` |

---

## Pull Request Workflow

### Branch Naming

```
feat/short-description     # New feature
fix/issue-number-desc      # Bug fix
docs/what-changed          # Documentation
refactor/module-name       # Code restructure
```

### PR Checklist

- [ ] `bun run typecheck` passes (zero errors)
- [ ] `bun run lint` passes
- [ ] `bun test` passes
- [ ] New code has corresponding tests (when applicable)
- [ ] Commit messages are clear and descriptive
- [ ] No unrelated changes bundled in

### Commit Messages

Follow conventional commits:

```
feat: add delta compression engine
fix: resolve semantic merge edge case with empty context
docs: update CLI reference table
refactor: extract pageindex into separate module
test: add grounding validation test cases
```

---

## Testing

```bash
bun test                       # Run all tests
bun test --filter "database"   # Run specific tests
bun test --watch               # Watch mode
```

### Writing Tests

Tests live alongside source files or in a `__tests__/` directory:

```typescript
import { describe, test, expect } from "bun:test";
import { DeltaEngine } from "../core/delta-engine.ts";

describe("DeltaEngine", () => {
  test("computeDelta produces valid patch", () => {
    const engine = new DeltaEngine();
    const delta = engine.computeDelta("hello world", "hello universe");
    expect(delta).toContain("universe");
  });
});
```

---

## Building Binaries

```bash
bun run build:bin:linux   # Linux x64
bun run build:bin:mac     # macOS ARM64
bun run build:bin:win     # Windows x64
bun run build:all         # All platforms
```

Binaries are compiled with `bun build --compile` and output to `.github/` or `dist/`.

---

## Extending CVC

### Adding a New LLM Provider

1. Create `src/adapters/your-provider.ts`
2. Implement the adapter interface (see `anthropic.ts` for reference)
3. Register in the provider map in `src/agent/llm.ts`
4. Add environment variable support in `src/core/models.ts`

### Adding a New CLI Command

1. Add the command definition in `src/cli.ts` using Commander.js
2. Wire it to the appropriate operation in `src/operations/`
3. Add MCP tool exposure in `src/mcp-server.ts` if applicable

### Adding a New Hook Event

1. Add the event name to `HookEvent` union type in `src/agent/hooks.ts`
2. Fire the hook at the appropriate point with `runHooks(event, payload)`
3. Document the event in the hooks table in `README.md`
