Contributing

Welcome

Thank you for considering contributing to Rule Engine JS! This guide will help you get started.

Setup

Clone, install, and verify

Contribute

Bug fixes, features, docs

Test

Write and run tests

Submit

Create pull requests

Quick Start

1. Fork and Clone

# Fork the repository on GitHub, then clone
git clone https://github.com/YOUR_USERNAME/rule-engine-js.git
cd rule-engine-js

# Add upstream
git remote add upstream https://github.com/crafts69guy/rule-engine-js.git

2. Install Dependencies

npm install

# Verify setup
npm test
npm run lint
npm run build

3. Development Commands

npm run dev           # Development mode with watch
npm run test:watch    # Tests in watch mode
npm run lint:fix      # Auto-fix linting issues
npm run format        # Format code with Prettier

Project Structure

rule-engine-js/
├── src/
│   ├── core/          # RuleEngine, PathResolver, StatefulRuleEngine
│   ├── operators/     # All operator implementations
│   ├── helpers/       # Rule building helpers
│   └── utils/         # Utility functions
├── tests/
│   ├── unit/          # Unit tests
│   ├── integration/   # Integration tests
│   └── e2e/          # End-to-end tests
└── docs/             # Documentation (Mintlify)

Contribution Types

🐛 Bug Fixes
✨ Features
📚 Documentation
🔧 Operators

Process:

Search existing issues
Create test case that reproduces bug
Fix the bug
Ensure all tests pass
Update docs if needed

git checkout -b fix/issue-description
# Make changes
npm test
git commit -m "fix: description"

Commit Convention

We follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

feat: New feature
fix: Bug fix
docs: Documentation
style: Code style (formatting)
refactor: Code refactoring
perf: Performance improvement
test: Adding/modifying tests
chore: Maintenance tasks
security: Security fixes

Examples:

feat(operators): add between operator for range checking

fix(core): resolve memory leak in path cache

docs(security): add security best practices guide

perf(cache): optimize expression cache hit rate

test(operators): add comprehensive regex operator tests

Code Standards

JavaScript Style

// ✅ Good
const engine = createRuleEngine();
const rule = rules.and(
  rules.gte('age', 18),
  rules.eq('status', 'active')
);

// Use template literals
const errorMsg = `Operator '${name}' failed`;

// Destructuring
const { success, error } = result;

// JSDoc for public APIs
/**
 * Evaluates a rule expression
 * @param {Object} rule - Rule expression
 * @param {Object} context - Data context
 * @returns {Object} Evaluation result
 */
function evaluateExpr(rule, context) {
  // Implementation
}

// ❌ Avoid
var engine = createRuleEngine(); // Use const/let
const r = rules.eq('n', 'John'); // Be descriptive
const msg = 'Error: ' + name; // Use template literals

Error Handling

// ✅ Proper error handling
if (!rule || typeof rule !== 'object') {
  throw new ValidationError('Rule must be a non-null object');
}

// Validate early
function evaluate(rule, context) {
  if (!context) {
    throw new ValidationError('Context is required');
  }
  // Proceed
}

Testing

Test Structure

describe('Feature Name', () => {
  let engine;

  beforeEach(() => {
    engine = createRuleEngine();
  });

  it('should handle valid input', () => {
    const rule = { eq: ['name', 'John'] };
    const context = { name: 'John' };

    const result = engine.evaluateExpr(rule, context);

    expect(result.success).toBe(true);
  });

  it('should handle null gracefully', () => {
    const rule = { eq: ['name', 'John'] };
    const context = { name: null };

    const result = engine.evaluateExpr(rule, context);

    expect(result.success).toBe(false);
  });
});

Test Requirements

100% coverage for new features
Test edge cases - null, undefined, empty
Test errors - invalid inputs
Test performance - no regressions

Pull Request Process

Before Creating PR

# 1. Ensure tests pass
npm test
npm run lint
npm run build

# 2. Rebase on latest main
git fetch upstream
git rebase upstream/main

# 3. Push to your fork
git push origin feature/your-feature

PR Checklist

PR Template

## Description
Brief description of changes.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation

## Testing
- [ ] Added tests
- [ ] All tests pass

## Related Issues
Closes #123

Security

Reporting Vulnerabilities: Do not open public issues for security vulnerabilities. Email: crafts69guy@gmail.com Include:

Reproduction steps
Impact assessment
Possible fixes (if known)

Security Testing:

it('should prevent prototype pollution', () => {
  const malicious = {
    "__proto__": { isAdmin: true }
  };

  const rule = { eq: ['__proto__.isAdmin', true] };
  const result = engine.evaluateExpr(rule, malicious);

  expect(result.success).toBe(false);
  expect(Object.prototype.isAdmin).toBeUndefined();
});

Issue Guidelines

Before Creating Issue

Search existing issues - Avoid duplicates
Check documentation - Verify not covered
Test latest version - Ensure issue exists
Create minimal reproduction - Simplest case

Bug Report

**Bug Description**
Clear description of the bug.

**To Reproduce**
1. Create rule `{ eq: ['field', 'value'] }`
2. Evaluate with context `{ field: 'value' }`
3. See error

**Expected Behavior**
What you expected to happen.

**Actual Behavior**
What actually happened.

**Environment**
- Rule Engine JS version: 1.0.3
- Node.js version: 18.15.0
- OS: Ubuntu 20.04

Feature Request

**Problem**
Description of the problem.

**Solution**
What you want to happen.

**Use Case**
How this feature helps.

**Example API**
```javascript
const rule = rules.newOperator('field', 'value');

---

## Labels

**Type:**
- `bug` - Something isn't working
- `enhancement` - New feature
- `documentation` - Docs improvements
- `performance` - Performance improvements
- `security` - Security issues

**Priority:**
- `critical` - Severe bugs/security
- `high` - Important bugs/features
- `medium` - Standard bugs/features
- `low` - Minor improvements

**Status:**
- `good first issue` - Good for newcomers
- `help wanted` - Extra attention needed
- `blocked` - Waiting on dependencies

---

## Best Practices

<AccordionGroup>
  <Accordion title="1. Start Small">
    Begin with simple contributions like docs or good first issues
  </Accordion>

  <Accordion title="2. Communicate Early">
    Discuss ideas in issues before implementing
  </Accordion>

  <Accordion title="3. Test Thoroughly">
    Cover edge cases and error conditions
  </Accordion>

  <Accordion title="4. Document Well">
    Help others understand your code
  </Accordion>

  <Accordion title="5. Be Patient">
    Reviews take time, feedback improves quality
  </Accordion>

  <Accordion title="6. Stay Involved">
    Help maintain your contributions
  </Accordion>
</AccordionGroup>

---

## Community

### Communication Channels

- **GitHub Issues** - Bug reports and feature requests
- **GitHub Discussions** - Questions and ideas
- **Pull Requests** - Code contributions
- **Email** - crafts69guy@gmail.com for security

### Code of Conduct

- **Be respectful** and professional
- **Be constructive** in feedback
- **Be patient** with new contributors
- **Help others learn** and grow

---

## Recognition

Contributors are recognized in:

- **CONTRIBUTORS.md** - All contributors
- **GitHub releases** - Release notes acknowledgments
- **Documentation** - Credit for major contributions

---

## Resources

<CardGroup cols={2}>
  <Card title="GitHub Repo" icon="github" href="https://github.com/crafts69guy/rule-engine-js">
    Source code and issues
  </Card>
  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete API documentation
  </Card>
  <Card title="Examples" icon="code" href="/examples/basic-rules">
    Usage examples
  </Card>
  <Card title="Changelog" icon="clock-rotate-left" href="/changelog">
    Version history
  </Card>
</CardGroup>

---

## Contact

**Maintainer:** Crafts 69 Guy

**Email:** crafts69guy@gmail.com

**GitHub:** [@crafts69guy](https://github.com/crafts69guy)

---

## Thank You

Thank you for contributing to Rule Engine JS! Whether you're fixing bugs, adding features, improving docs, or helping others, every contribution matters.

**Happy coding! 🚀**

Get Started

Core Concepts

Operators

Guides

Contributing

Welcome

Setup

Contribute

Test

Submit

Quick Start

1. Fork and Clone

2. Install Dependencies

3. Development Commands

Project Structure

Contribution Types

Commit Convention

Code Standards

JavaScript Style

Error Handling

Testing

Test Structure

Test Requirements

Pull Request Process

Before Creating PR

PR Checklist

PR Template

Security

Issue Guidelines

Before Creating Issue

Bug Report

Feature Request

Get Started

Core Concepts

Operators

Guides

Contributing

​Welcome

Setup

Contribute

Test

Submit

​Quick Start

​1. Fork and Clone

​2. Install Dependencies

​3. Development Commands

​Project Structure

​Contribution Types

​Commit Convention

​Code Standards

​JavaScript Style

​Error Handling

​Testing

​Test Structure

​Test Requirements

​Pull Request Process

​Before Creating PR

​PR Checklist

​PR Template

​Security

​Issue Guidelines

​Before Creating Issue

​Bug Report

​Feature Request

Welcome

Quick Start

1. Fork and Clone

2. Install Dependencies

3. Development Commands

Project Structure

Contribution Types

Commit Convention

Code Standards

JavaScript Style

Error Handling

Testing

Test Structure

Test Requirements

Pull Request Process

Before Creating PR

PR Checklist

PR Template

Security

Issue Guidelines

Before Creating Issue

Bug Report

Feature Request