# Contributing to igcv3

First off, thank you for considering contributing to igcv3! 🎉

## Code of Conduct

Be respectful and constructive. We're all here to build something useful.

## How Can I Contribute?

### Reporting Bugs

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

When creating a bug report, include:

- Your environment (OS, Node.js version, igcv3 version)
- Steps to reproduce
- Expected vs actual behavior
- Relevant logs or error messages

Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md).

### Suggesting Features

Feature requests are welcome! Please use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md).

Consider:

- Does it fit the project scope (PKI/certificate management)?
- Is it useful for other users, not just your specific case?

### Pull Requests

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests and linting
5. Commit with a clear message
6. Push and open a PR

## Development Setup

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

# Install dependencies
npm install

# Build
npm run build

# Link for local testing
npm link
```

## Running Tests

```bash
# Unit tests (Jest)
npm test
npm test -- --watch      # Watch mode
npm test -- --coverage   # With coverage

# E2E/integration tests (PowerShell)
./tests/main.ps1              # All suites
./tests/main.ps1 -Suite 04    # Single suite
./tests/main.ps1 -Verbose     # With output

Note: interactive flows are exercised in the PowerShell suites; unit tests focus on pure logic.
```

## Code Style

### Language

- **Code**: English (variables, functions, comments, JSDoc)
- **Commits**: English, imperative mood (`Add feature`, not `Added feature`)

### TypeScript

- Strict mode enabled (`noImplicitAny`, etc.)
- No `any` unless absolutely necessary and justified
- Use discriminated unions for type-safe configs

### Formatting

- ESLint + Prettier enforced
- Run `npm run lint` before committing

### Commit Messages

Follow this format (inspired by conventional commits):

```text
[MAJ.MIN.PATCH ::: SCOPE] Summary

• Feat: New feature description
• Fix: Bug fix description
• Docs: Documentation changes
• Refactor: Code refactoring
• Test: Test additions/changes
• Chore: Build/tooling changes
```

Example:

```text
[1.2.0 ::: GENERATE] Add Ed25519 support

• Feat: Ed25519 key generation via @peculiar/x509
• Feat: New 'modern-ed25519' preset
• Test: Integration tests for Ed25519 CSR generation
• Docs: Update README with Ed25519 examples
```

## Project Structure

```text
src/
├── commands/        # CLI command implementations
├── config/          # Configuration loading & validation
├── lib/             # Business logic
├── services/        # PKI services (crypto backends)
└── utils/           # Shared utilities
```

### Key Design Principles

1. **Modular Commands**: Large commands split into focused modules (~200 lines each)
2. **Facade Pattern**: `PkiService` provides unified API over multiple crypto backends
3. **Config Cascading**: Custom → Local → User → System defaults
4. **Hybrid CLI**: Commands work as both CLI tools and interactive wizards

## Questions?

Feel free to open an issue for questions or discussions.