feat(evaluators): add nested $ref resolution scenarios

[aepfli]

Summary

Adds @evaluator-refs and @evaluator-ref-edge-cases tagged scenarios to targeting.feature covering recursive $ref resolution from flagd#1875.

New Tags

• @evaluator-refs — added to the existing basic evaluator reuse scenario (previously untagged)
• @evaluator-ref-edge-cases — for the new nested resolution scenario

Changes

Existing scenario tagged

The existing "Evaluator reuse" scenario now has @evaluator-refs so SDK implementations can explicitly opt in.

New: Nested $ref resolution (nested-ref-targeted-flag)

A new is_privileged evaluator in evaluator-refs.json references is_ballmer via $ref:

"is_privileged": {
  "or": [
    {"$ref": "is_ballmer"},
    {"==": ["admin", {"var": ["role"]}]}
  ]
}

The nested-ref-targeted-flag uses $ref: is_privileged, requiring two levels of resolution. Tests:

context	expected
email = ballmer@macrosoft.com	privileged (via nested is_ballmer)
role = admin	privileged (via direct admin check)
email = other@example.com	standard (neither condition met)

Related

• flagd#1875 — root bug report
• flagd-evaluator#22 — evaluator tracking issue

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request expands the test suite for flag evaluation by introducing scenarios that validate nested $ref resolution within evaluators. It ensures that the system correctly handles complex referencing patterns, improving the robustness of feature flag targeting logic and addressing a reported bug related to recursive $ref usage.

Highlights

• New Nested $ref Resolution Scenarios: Added new tagged scenarios (@evaluator-refs, @evaluator-ref-edge-cases) to targeting.feature to cover recursive $ref resolution, addressing flagd#1875.
• New is_privileged Evaluator: Introduced a new is_privileged evaluator in evaluator-refs.json that demonstrates two levels of $ref resolution by referencing is_ballmer.
• Existing Scenario Tagged: The existing "Evaluator reuse" scenario in targeting.feature was tagged with @evaluator-refs for explicit SDK opt-in.

Changelog

• flags/evaluator-refs.json
  • Added a new flag nested-ref-targeted-flag to test multi-level $ref resolution.
  • Introduced an is_privileged evaluator that uses $ref to another evaluator (is_ballmer) and an additional condition.
• gherkin/targeting.feature
  • Applied the @evaluator-refs tag to the existing 'Evaluator reuse' scenario.
  • Added a new scenario 'Nested evaluator ref resolution' tagged with @evaluator-refs and @evaluator-ref-edge-cases to test the new nested $ref logic.

Activity

• No human activity has been recorded on this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request successfully introduces nested $ref resolution scenarios, addressing the issue described in flagd#1875. The evaluator-refs.json file correctly defines the new nested-ref-targeted-flag and the is_privileged evaluator, which leverages a nested $ref to is_ballmer. The targeting.feature file includes a new scenario, "Nested evaluator ref resolution," with comprehensive examples that validate the expected behavior for different context inputs. The addition of @evaluator-refs and @evaluator-ref-edge-cases tags also improves test organization. Overall, the changes are well-implemented and provide good test coverage for the new functionality.

[aepfli]

relates too open-feature/flagd#1875

[toddbaert]

I'm not sure we want to support $refs that reference $refs.

If we do, are we only going to support it naively, as shown here, where "dependency" refs must appear first? I worry that this could be problematic because of non-deterministic ordering of JSON keys. If some server serializes $evaluators they might not be rendered in the correct order. That's what point 2 here is mentioning: open-feature/flagd#1875

[aepfli]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces support for nested evaluator references within flag targeting configurations. It adds a new flag, nested-ref-targeted-flag, and a composite evaluator, is_privileged, which utilizes a $ref to another evaluator. Corresponding Gherkin test scenarios have been added to validate the resolution of these nested references against various context attributes. I have no feedback to provide.

[aepfli]

Good catch, @toddbaert! Inlined the is_ballmer condition directly into is_privileged in 82d5489, removing the nested $ref entirely. The scenario still tests evaluator ref resolution (nested-ref-targeted-flag uses $ref: is_privileged), just without the declaration-order dependency.