# Contributing to kg6-codex

Thank you for your interest in contributing to kg6-codex! This document provides guidelines and information for contributors.

## Getting Started

### Prerequisites

- Node.js 20+ 
- npm or yarn
- Git
- Docker (optional, for containerized development)

### Development Setup

1. **Fork and Clone**
   ```bash
   git clone https://github.com/your-username/ai-developer-assistant.git
   cd ai-developer-assistant
   ```

2. **Install Dependencies**
   ```bash
   npm install
   ```

3. **Environment Setup**
   ```bash
   cp env.example .env
   # Edit .env with your configuration
   ```

4. **Build and Test**
   ```bash
   npm run build
   npm test
   ```

## Architecture Overview

kg6-codex follows **Hexagonal Architecture** (Ports & Adapters):

```
src/
├── domain/           # Core business logic (framework-agnostic)
│   ├── entities/     # Domain entities (Diff, ReviewComment, etc.)
│   ├── ports/        # Interface definitions (contracts)
│   └── usecases/     # Business use cases (application logic)
├── adapters/         # External integrations
│   ├── inbound/      # Driving adapters (CLI, API, IDE)
│   └── outbound/     # Driven adapters (Git, LLM, GitHub)
├── config/           # Configuration management
└── utils/            # Shared utilities
```

### Key Principles

1. **Dependency Inversion**: Core business logic depends on abstractions (ports), not concrete implementations
2. **Separation of Concerns**: Clear boundaries between domain, application, and infrastructure
3. **Testability**: Each layer can be tested independently
4. **Extensibility**: New adapters can be added without changing core logic

## Development Guidelines

### Code Style

- Use TypeScript with strict mode enabled
- Follow the existing code style and patterns
- Use meaningful variable and function names
- Add JSDoc comments for public APIs
- Prefer composition over inheritance

### Git Workflow

1. **Create a Feature Branch**
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. **Make Changes**
   - Write code following the architecture principles
   - Add tests for new functionality
   - Update documentation as needed

3. **Commit Messages**
   Use conventional commit format:
   ```
   feat: add new security scanner for SQL injection
   fix: resolve memory leak in LLM adapter
   docs: update README with new configuration options
   test: add unit tests for GitAdapter
   ```

4. **Push and Create PR**
   ```bash
   git push origin feature/your-feature-name
   ```

### Testing

- Write unit tests for all new functionality
- Maintain or improve test coverage
- Use descriptive test names
- Test both success and error scenarios

```typescript
describe('GitAdapter', () => {
  it('should parse diff results correctly', async () => {
    // Arrange
    const adapter = new GitAdapter();
    const mockDiff = 'diff --git a/file.ts b/file.ts\n...';
    
    // Act
    const result = await adapter.parseDiffResult(mockDiff);
    
    // Assert
    expect(result).toHaveLength(1);
    expect(result[0].filePath).toBe('file.ts');
  });
});
```

## Adding New Features

### 1. New CLI Command

```typescript
// src/cli/commands/NewCommand.ts
export class NewCommand extends BaseCommand {
  constructor() {
    super('new-command', 'Description of the new command');
    // Add command options
  }

  protected async execute(options: any): Promise<void> {
    // Implement command logic
  }
}
```

### 2. New Domain Entity

```typescript
// src/domain/entities/NewEntity.ts
export interface NewEntity {
  readonly id: string;
  readonly property: string;
  // Define readonly properties
}

export class NewEntityImpl implements NewEntity {
  constructor(
    public readonly id: string,
    public readonly property: string
  ) {}
}
```

### 3. New Adapter

```typescript
// src/adapters/outbound/NewAdapter.ts
export class NewAdapter implements NewPort {
  async performOperation(): Promise<Result> {
    // Implement adapter logic
  }
}
```

### 4. New Use Case

```typescript
// src/domain/usecases/NewUseCase.ts
export class NewUseCase {
  constructor(
    private readonly adapter: NewPort
  ) {}

  async execute(options: NewOptions): Promise<NewResult> {
    // Implement business logic
  }
}
```

## Testing Guidelines

### Unit Tests

- Test individual components in isolation
- Mock external dependencies
- Use descriptive test names
- Follow AAA pattern (Arrange, Act, Assert)

### Integration Tests

- Test component interactions
- Use real adapters where appropriate
- Test error scenarios

### Test Structure

```typescript
describe('ComponentName', () => {
  describe('methodName', () => {
    it('should handle success case', () => {
      // Test implementation
    });

    it('should handle error case', () => {
      // Test implementation
    });
  });
});
```

## Documentation

### Code Documentation

- Add JSDoc comments for public APIs
- Include parameter and return type descriptions
- Provide usage examples where helpful

```typescript
/**
 * Generates a commit message based on code changes
 * @param diffs - Array of code differences
 * @param options - Generation options
 * @returns Promise resolving to commit message
 * @example
 * ```typescript
 * const message = await generateCommitMessage(diffs, { style: 'conventional' });
 * ```
 */
async generateCommitMessage(diffs: Diff[], options: CommitOptions): Promise<string> {
  // Implementation
}
```

### README Updates

- Update README.md for new features
- Add configuration examples
- Include usage examples

## Bug Reports

When reporting bugs, please include:

1. **Environment Information**
   - Node.js version
   - Operating system
   - kg6-codex version

2. **Steps to Reproduce**
   - Clear, numbered steps
   - Expected vs actual behavior

3. **Additional Context**
   - Error messages/logs
   - Configuration files (remove sensitive data)
   - Screenshots if applicable

## Feature Requests

When suggesting features:

1. **Problem Description**
   - What problem does this solve?
   - Who would benefit from this feature?

2. **Proposed Solution**
   - How should it work?
   - Any specific requirements or constraints?

3. **Alternatives Considered**
   - What other solutions have you considered?

## Code Review Process

### For Contributors

1. Ensure your PR is focused and addresses a single issue
2. Write clear commit messages
3. Add tests for new functionality
4. Update documentation as needed
5. Respond to review feedback promptly

### For Reviewers

1. Check code quality and architecture compliance
2. Verify tests are adequate
3. Ensure documentation is updated
4. Test the changes locally if needed
5. Provide constructive feedback

## Release Process

1. **Version Bumping**
   - Use semantic versioning (MAJOR.MINOR.PATCH)
   - Update package.json and CHANGELOG.md

2. **Release Notes**
   - Document new features
   - List bug fixes
   - Note breaking changes

3. **Distribution**
   - Tag releases in Git
   - Publish to npm
   - Update documentation

## Community Guidelines

### Be Respectful

- Use welcoming and inclusive language
- Be respectful of differing viewpoints and experiences
- Accept constructive criticism gracefully
- Focus on what is best for the community

### Be Collaborative

- Help others when you can
- Share knowledge and best practices
- Participate in discussions constructively
- Welcome newcomers and help them get started

## Getting Help

- [GitHub Discussions](https://github.com/kg6-oss/kg6-codex/discussions)
- [GitHub Issues](https://github.com/kg6-oss/kg6-codex/issues)
- [Email](mailto:maintainers@ai-dev-assistant.com)
- [Documentation](https://github.com/kg6-oss/kg6-codex/wiki)

## License

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

---

Thank you for contributing to kg6-codex!