Missing Changelog for Version 7.x - Unofficial Community Changelog

### Summary

Version 7.x of `json-rules-engine` represents a major version bump from 6.x, but there is no official changelog documenting the changes. This makes it difficult for users to safely upgrade and understand what breaking changes they need to account for.

The CHANGELOG.md file in the package only goes up to version 6.1.0, leaving versions 6.2.0 through 7.3.1 completely undocumented.

### Impact

- Users are hesitant to upgrade due to unknown breaking changes
- Security vulnerability in `jsonpath-plus` (CVE-2024-21534) requires upgrading to v7+
- Issue #372 discusses v7 design but doesn't provide a migration guide
- Existing issue about "list of breaking changes v7" shows community need for this information

### Unofficial Community Changelog (6.5.0 → 7.3.1)

⚠️ **DISCLAIMER**: This changelog is based on code comparison and TypeScript definition analysis. It is **NOT official** and may be incomplete. Users should perform their own testing before upgrading in production environments.

---

#### 🔴 BREAKING CHANGES

**1. Node.js Version Requirement**
```diff
- v6.5.0: No engine requirement
+ v7.x: Requires Node.js >= 18.0.0
```

**2. Security: jsonpath-plus Dependency Updated**
```diff
- v6.5.0: jsonpath-plus@^7.2.0 (vulnerable to RCE - CVE-2024-21534)
+ v7.x: jsonpath-plus@^10.3.0 (patched)
```
**This is the primary reason to upgrade to v7.**

**3. Removed Dependency**
```diff
- v6.5.0: lodash.isobjectlike@^4.0.0
+ v7.x: Removed (replaced with internal implementation)
```
*Impact: Internal change only, should not affect user code*

**4. API Change: `addOperator()` Return Type**
```typescript
// v6.5.0
engine.addOperator(operator): Map

// v7.x
engine.addOperator(operator): void
```
**Impact**: Code that uses the return value of `addOperator()` will break.

**Example of breaking code**:
```typescript
// This will break in v7
const operators = engine.addOperator('customOp', callback);
operators.get('customOp'); // ❌ operators is now void

// Instead, operators should be tracked separately
engine.addOperator('customOp', callback); // ✅ Returns void in v7
```

**5. Deprecation: `rule.ruleEvent` Property**
```typescript
// v6.5.0
rule.event // ✅ Available

// v7.x
rule.ruleEvent // ⚠️ Deprecated (still works but shows warning)
rule.event // ✅ Preferred
```
*Impact: Soft breaking change - existing code using `rule.event` continues to work*

**6. Event Handler Type Signature**
```typescript
// v6.5.0
engine.on('success', handler: EventHandler): this
engine.on('failure', handler: EventHandler): this

// v7.x
engine.on(eventName: string, handler: EventHandler): this
```
*Impact: More flexible, backwards compatible for JavaScript users. TypeScript users get better type inference.*

---

#### ✨ NEW FEATURES

**7. Operator Decorators** (Major new feature)

New APIs:
```typescript
engine.addOperatorDecorator(decorator: OperatorDecorator): void
engine.addOperatorDecorator(
decoratorName: string,
callback: OperatorDecoratorEvaluator
): void
engine.removeOperatorDecorator(decorator: OperatorDecorator | string): boolean

// New class
class OperatorDecorator {
constructor(
name: string,
evaluator: OperatorDecoratorEvaluator,
validator?: (factValue: A) => boolean
)
}
```

Allows wrapping operators with additional logic for preprocessing, logging, or custom validation.

**New distribution files added**:
- `dist/operator-decorator.js`
- `dist/operator-map.js`
- `dist/engine-default-operator-decorators.js`

**8. Enhanced Result Types**

New TypeScript types for better result handling:
- `TopLevelConditionResult`
- `RuleResultSerializable`
- `ConditionResultProperties`
- `BooleanConditionResultProperties`
- Various condition result types (`AllConditionsResult`, `AnyConditionsResult`, `NotConditionsResult`, `ConditionReferenceResult`)

Enhanced `RuleResult` interface:
```typescript
interface RuleResult {
toJSON(): string;
toJSON(stringify: T): T extends true ? string : RuleResultSerializable;
}
```

---

#### 📝 MIGRATION CHECKLIST

When upgrading from v6.x to v7.x:

1. ✅ Verify Node.js version is >= 18.0.0
2. 🔍 Search codebase for `addOperator()` usage and remove any code that depends on its return value
3. 🔍 (Optional) Search for `rule.ruleEvent` and replace with `rule.event`
4. ⚠️ **IMPORTANT**: Update Jest/Vitest configs that map `jsonpath-plus` to use v10.3.0 CommonJS build (see #417)
5. 🧪 Run full test suite
6. 🔬 Test in a staging environment before production deployment

**Search commands**:
```bash
# Find addOperator usage
grep -r "addOperator" --include="*.ts" --include="*.js"

# Find deprecated ruleEvent usage
grep -r "\.ruleEvent" --include="*.ts" --include="*.js"
```

---

#### ⚠️ KNOWN ISSUE: ESM/CommonJS Compatibility (#417)

As reported in [Issue #417](https://github.com/CacheControl/json-rules-engine/issues/417), `jsonpath-plus@10.x` serves ESM modules for browsers, but `json-rules-engine` v7.3.1 only supports CommonJS. This causes issues in browser environments and test runners like Jest/Vitest.

**Workaround for Jest/Vitest**:
```javascript
// jest.config.js or vitest.config.js
moduleNameMapper: {
"^jsonpath-plus$":
"/node_modules/.pnpm/jsonpath-plus@10.3.0/node_modules/jsonpath-plus/dist/index-node-cjs.cjs"
}
```

**Impact**: If you're running `json-rules-engine` in browser tests, you'll need to configure your test runner to use the CommonJS build of `jsonpath-plus`.

---

### Request to Maintainers

**Could the maintainers please**:

1. **Update the CHANGELOG.md** with official release notes for versions 6.2.0 through 7.3.1
2. **Document any breaking changes** that were introduced
3. **Provide a migration guide** from v6 to v7
4. **Consider publishing release notes** for future versions on the GitHub Releases page

Having an official changelog is crucial for:
- Understanding breaking changes before upgrading
- Planning migration efforts
- Maintaining trust in semantic versioning
- Helping users upgrade safely to get the security fix for `jsonpath-plus`

The security vulnerability in `jsonpath-plus` makes upgrading to v7 important, but the lack of documentation makes users hesitant to do so.

---

### How This Changelog Was Created

This unofficial changelog was created by:
1. Comparing TypeScript definitions (`types/index.d.ts`) between v6.5.0 and v7.3.1
2. Analyzing `package.json` differences (dependencies, engines)
3. Comparing distribution files (`dist/` directory)
4. Reviewing [Issue #372](https://github.com/CacheControl/json-rules-engine/issues/372) for v7 design goals
5. Testing the changes in a real project

**⚠️ This is NOT an exhaustive list.** There may be additional changes, bug fixes, or subtle behavior differences not captured here.

---

### Community Contributions Welcome

If others have found additional breaking changes or differences not listed here, please comment below so we can build a more complete picture of what changed in v7.

---

### Related Issues

- #372 - version 7 - Design
- #408 - list of breaking changes v7 (community request for changelog)
- #417 - jsonpath-plus expects browser to use ESM (ESM/CommonJS compatibility issue)
- #379 - PR: fix(deps): update dependency jsonpath-plus to 10.0.0 due to vulnerability

### References

- [CVE-2024-21534 - jsonpath-plus RCE vulnerability](https://github.com/advisories/GHSA-pppg-cpfq-h7wr)
- [GitHub Advisory Database - jsonpath-plus](https://github.com/advisories/GHSA-hw8r-x6gr-5gjp)

---

**Community Members**: Please add your findings in the comments if you discover additional changes during your upgrade process.

**Maintainers**: Thank you for this excellent library! An official changelog would be greatly appreciated by the community. 🙏