# Contributing to Bangstack

Thank you for your interest in contributing to Bangstack! We welcome contributions from the community.

## Code of Conduct

Be respectful, inclusive, and considerate in all interactions. We're here to build something great together.

## How to Contribute

### Reporting Bugs

If you find a bug, please open an issue with:
- A clear title and description
- Steps to reproduce
- Expected vs actual behavior
- Your environment (OS, Node version, etc.)
- Workflow file (if applicable)

### Suggesting Features

We love feature suggestions! Please open an issue with:
- A clear description of the feature
- Use cases and examples
- Why it would be valuable

### Pull Requests

1. **Fork the repository** and create your branch from `main`
2. **Make your changes** with clear, descriptive commits
3. **Add tests** for new functionality
4. **Update documentation** if needed
5. **Run the test suite** to ensure everything passes
6. **Submit a pull request**

## Development Setup

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

# Install dependencies
npm install

# Build the project
npm run build

# Link for local testing
npm link

# Run tests
npm test

# Watch mode for development
npm run dev
```

## Project Structure

```
bangstack/
├── src/
│   ├── types/          # TypeScript type definitions
│   ├── parser/         # YAML workflow parser
│   ├── engine/         # Workflow execution engine
│   ├── generators/     # Code generators
│   │   ├── frontend/   # Frontend generators
│   │   ├── backend/    # Backend generators
│   │   ├── docs/       # Documentation generators
│   │   └── types.ts    # Generator interfaces
│   └── cli/           # CLI commands
├── examples/          # Example workflows
├── docs/             # Documentation
└── tests/            # Tests
```

## Adding a New Generator

To add a new generator:

1. **Create the generator file** in the appropriate directory:
   ```typescript
   // src/generators/frontend/vue-generator.ts
   import { FrontendGenerator, GeneratorContext, GenerationResult } from '../types';

   export class VueGenerator implements FrontendGenerator {
     id = 'vue-frontend';
     name = 'Vue.js Frontend Generator';
     description = 'Generates Vue 3 components';
     framework = 'vue';

     generate(context: GeneratorContext): GenerationResult {
       // Your generation logic
       return { files: [] };
     }
   }
   ```

2. **Register the generator** in `src/generators/index.ts`:
   ```typescript
   import { VueGenerator } from './frontend/vue-generator';

   const vueGenerator = new VueGenerator();
   globalRegistry.registerFrontendGenerator(vueGenerator);
   ```

3. **Add tests** in the same directory:
   ```typescript
   // src/generators/frontend/vue-generator.test.ts
   describe('VueGenerator', () => {
     it('should generate Vue components', () => {
       // Your tests
     });
   });
   ```

4. **Update documentation** in README.md and relevant docs

## Testing

We use Jest for testing. Please ensure all tests pass before submitting a PR:

```bash
# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run specific test file
npm test -- vue-generator.test.ts

# Run with coverage
npm test -- --coverage
```

## Code Style

We use ESLint and Prettier for code formatting:

```bash
# Lint code
npm run lint

# Format code
npm run format
```

### Guidelines

- Use TypeScript for all new code
- Write clear, descriptive variable and function names
- Add JSDoc comments for public APIs
- Keep functions small and focused
- Follow existing code patterns

## Commit Messages

Use clear, descriptive commit messages:

```
feat: Add Vue.js frontend generator
fix: Handle empty workflow files correctly
docs: Update generator documentation
test: Add tests for React generator
refactor: Simplify DAG building logic
```

### Format

```
<type>: <subject>

[optional body]

[optional footer]
```

**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation
- `test`: Tests
- `refactor`: Code refactoring
- `style`: Formatting
- `chore`: Maintenance

## Documentation

When adding features, please update:

- **README.md** - Main documentation
- **docs/** - Detailed guides
- **Code comments** - Inline documentation
- **Examples** - Add workflow examples if relevant

## Questions?

Feel free to open an issue with the `question` label or start a discussion. We're here to help!

## License

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

---

Thank you for contributing to Bangstack! 🚀
