(feature) Flag dependencies with needs field

[thomaspoignant]

Requirements

Summary

Introduce a needs field in the flag configuration to allow a flag to declare dependencies on other flags. When a flag declares needs, it will only be evaluated if all its dependencies resolve to the expected values. If any dependency is not met, the flag is considered disabled and returns the disabled variation without evaluating targeting rules or defaultRule.

---

Motivation

Currently, there is no way to express that a flag should only be active if another flag is enabled. This leads to workarounds like duplicating targeting rules across flags or relying on application code to chain flag evaluations. A native needs field makes dependencies explicit, declarative, and statically analyzable — both at runtime and in the future UI.

A real example: a checkout-v2 flag only makes sense if payments-enabled is true. Without needs, there is no way to express that relationship in the flag config itself.

---

Proposed Format

The needs field is a list of conditions. Each entry declares a flag name and optionally an expected value. All conditions must be satisfied (AND semantics) for the flag to proceed to normal evaluation.

checkout-v2:
  needs:
    - flag: payments-enabled
      value: true
  variations:
    enabled: true
    disabled: false
  defaultRule:
    variation: disabled

value is optional for boolean flags — omitting it implicitly checks for true:

checkout-v2:
  needs:
    - flag: payments-enabled   # equivalent to value: true
  variations:
    enabled: true
    disabled: false
  defaultRule:
    variation: disabled

Multiple dependencies use AND semantics, matching GitHub Actions' needs behavior:

new-editor:
  needs:
    - flag: beta-program
      value: true
    - flag: user-plan
      value: enterprise
  variations:
    on: true
    off: false
  defaultRule:
    variation: off

needs acts as a pre-gate: if all conditions pass, normal evaluation continues (targeting rules → defaultRule). If any condition fails, the flag is immediately disabled.

needs check → targeting rules → defaultRule
     ↓ (any unmet)
  disabled variation

---

Behavior Specification

• Unmet dependency → the flag returns the disabled variation (same as a flag with disable: true). Targeting rules and defaultRule are not evaluated.
• Dependency resolution depth → one level only. needs resolves the direct parent flag's value but does not follow that flag's own needs transitively. This keeps evaluation predictable and avoids hard-to-debug chains.
• Cycle detection → circular dependencies (flag A needs flag B which needs flag A) must not work. When a parent flag is part of the needs field, we will ignore the parent needs.
• Missing flag → if a flag referenced in needs does not exist, the condition is treated as unmet and the flag is disabled.
• Same evaluation context → the dependency flag is evaluated using the same evaluation context as the dependent flag.

---

Impact on Existing Flags

This is a purely additive change. Flags without a needs field are unaffected.

---

Open Questions

• Should unmet needs be reported in the evaluation metadata (e.g. reason: DEPENDENCY_NOT_MET), to help with debugging and observability?