feat: support rule-based segments in local evaluation

[cre8ivejp]

Part of bucketeer-io/bucketeer#2722

Summary

Bucketeer server 2.3.0 introduced rule-based segments: a segment can define attribute-based rules in addition to its uploaded included-user list. A user belongs to the segment if they are in the list OR match any rule. Within a rule, clauses are AND-ed; across rules, OR. The backend delivers the rules to server SDKs inside the SegmentUsers message returned by the gateway's GetSegmentUsers endpoint.

This PR makes the Node server SDK's local evaluation honor those rules. It requires @bucketeer/evaluation 0.0.9 and a Bucketeer server 2.3.0+ to take effect.

Changes

• package.json / yarn.lock: bump @bucketeer/evaluation 0.0.8 → 0.0.9, which adds rules to the SegmentUsers proto and evaluates segment rules.
• src/objects/segment.ts: add the optional rules field to the SegmentUsers response model.
• src/cache/processor/converter.ts: toProtoSegmentUsers carries the rules into the cached proto, so both full-state and diff cache updates preserve them.
• src/evaluator/local.ts: rebuild Segment messages from the cached rules and pass them to the evaluator, so a flag rule with a SEGMENT clause matches users by rules as well as by user-ID list.

Evaluation semantics

• Segment membership = included-user list OR any rule matches.
• Clauses within a rule are AND-ed; rules are OR-ed.
• A SEGMENT clause with multiple segment IDs is OR.
• SEGMENT and FEATURE_FLAG operators inside segment rules fail closed.

Backward compatibility

• Segments without rules evaluate exactly as before (included-user list only).
• Servers older than 2.3.0 never send rules, so behavior with them is unchanged.

Tests

• Unit tests for the converter, cache, and evaluator, including AND/OR semantics, missing attributes, and list-only backward compat.
• An integration test covering the full data path: API response parse → cache processor → cache → evaluator input.
• New e2e scenarios in e2e/local_evaluation/evaluation_rule_based_segment.ts (multi-rule/multi-clause segments with varied operators, mixed list+rules segments, SEGMENT clause AND attribute clause, missing attributes, backward compat). Note: these require new fixtures in the e2e environment; the required configuration is documented at the top of the test file.

E2E tests: https://github.com/bucketeer-io/node-server-sdk/actions/runs/31152495702/job/92784909315

[Copilot]

Pull request overview

Adds support for Bucketeer server 2.3.0+ rule-based segments in the Node server SDK’s local evaluation path by propagating segment rules from the API response into the cache and then into the evaluator inputs (alongside the existing included-user list behavior).

Changes:

• Bump @bucketeer/evaluation to 0.0.9 to obtain proto + evaluation support for segment rules.
• Extend the SegmentUsers model + cache converter to carry rules through full/diff cache updates.
• Update local evaluator wiring to pass reconstructed Segment rule data to the evaluation engine; add unit/integration/e2e coverage for rule AND/OR semantics and backward compatibility.

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
package.json	Bumps @bucketeer/evaluation dependency to 0.0.9.
yarn.lock	Locks @bucketeer/evaluation@0.0.9 resolution/integrity.
src/objects/segment.ts	Adds optional rules to the SegmentUsers response model.
src/cache/processor/converter.ts	Carries SegmentUsers.rules into the cached proto via setRulesList.
src/evaluator/local.ts	Rebuilds Segment from cached rules and passes a segmentsMap into evaluateFeatures.
src/__tests__/utils/feature.ts	Adds createSegmentUsers helper to build ProtoSegmentUsers via the converter.
src/__tests__/evaluator/evaluator.ts	Adds unit tests for rule-based segment matching + list-only backward compatibility.
src/__tests__/cache/segements_user.ts	Adds cache put/get test ensuring proto rules survive round-trip.
src/__tests__/cache/processor/segementUsersCache/rules.ts	Adds integration test covering API parse → processor → cache → evaluator rule propagation.
src/__tests__/cache/processor/converter.ts	Adds converter tests validating proto rulesList output + missing-rules behavior.
e2e/local_evaluation/evaluation_rule_based_segment.ts	Adds e2e scenarios for multi-rule/multi-clause rule-based segments in local evaluation.
e2e/constants/constants.ts	Adds constants used by the new rule-based segment e2e tests.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated no new comments.

Suppressed comments (1)

e2e/local_evaluation/evaluation_rule_based_segment.ts:67

• Grammar: this comment reads awkwardly. Consider rephrasing to “Wait for the cache to become available” so it’s clear what the await is doing.

  // Waiting for the cache available
  await t.context.bktClient.waitForInitialization({ timeout: 5000 });

[duyhungtnn]

Nice works.

This PR LGTM