Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/workflows/expressions.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ Notes on the newer filters:

`and` and `or` return `true` or `false` and evaluate their right side only when the left side does not decide the result: `and` skips it when the left side is false, and `or` skips it when the left side is true. A condition can therefore guard a filter that would fail on an empty value. `{{ inputs.payload != '' and (inputs.payload | from_json | length) }}` is false for an empty optional `payload` instead of failing the run on invalid JSON. When the right side is evaluated, its errors still fail the run.

Operators bind from loosest to tightest as `or`, `and`, `not`, then the comparisons. All comparisons (`==`, `!=`, `>`, `<`, `>=`, `<=`, `in`, `not in`) share one level and are evaluated left to right; none has priority over another. `{{ a == b > 0 }}` therefore means `{{ (a == b) > 0 }}`. To combine comparisons, use parentheses or `and`/`or`.
Operators bind from loosest to tightest as `or`, `and`, `not`, then the comparisons. All comparisons (`==`, `!=`, `>`, `<`, `>=`, `<=`, `in`, `not in`) share one level and chain as in Python and Jinja2: `{{ 0 <= inputs.n <= 10 }}` means `{{ 0 <= inputs.n and inputs.n <= 10 }}`, with the shared operand evaluated once and evaluation stopping at the first false pair — a later operand is evaluated only when every pair before it held, with the same guard behavior as `and`. Explicit parentheses end a chain: `{{ (0 <= inputs.n) <= 10 }}` compares the grouped `true`/`false` result with `10`, exactly as in Python.

The body of every `{{ }}` block must be a valid expression. Text that is not one, such as prose (`{{ some text }}`), a key with characters other than letters, digits, `_` and `-` (`{{ inputs.weird:key }}`), or arithmetic (`{{ count + 1 }}`), raises a `ValueError` naming the offending token. Numbers may be written as `5`, `-5`, `+5`, `1_000`, `0.5`, `.5`, `5.`, or `1.5e3`.

Expand Down
76 changes: 56 additions & 20 deletions src/specify_cli/workflows/expressions/engine.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,12 @@
parsed here. The language is the same with these deliberate differences, all
documented in https://github.github.io/spec-kit/workflows/expressions.html:

* All comparison operators share one precedence level and group left to right
(``a == b > 0`` is ``(a == b) > 0``). The former engine's operator scan order
gave them accidental priorities; parenthesize to combine comparisons.
* All comparison operators share one precedence level and chain like Python
and Jinja2 (``0 <= n <= 10`` is ``0 <= n and n <= 10``, with ``n`` evaluated
once and evaluation stopping at the first false pair). The former engine's
operator scan order gave them accidental priorities and compared a boolean
to the next operand; explicit parentheses still end a chain, so
``(0 <= n) <= 10`` compares the grouped result, exactly as in Python.
* Text that is not an expression -- prose inside ``{{ }}``, path keys with
characters outside ``[\\w-]`` -- is a syntax error instead of a path lookup,
which could resolve an existing key.
Expand Down Expand Up @@ -207,6 +210,13 @@ def path(self, token: Token) -> tuple[str, str]:
return ("path", str(token))

def group(self, inner: Any) -> Any:
# Parentheses end a comparison chain: ``(0 <= n) <= 10`` compares the
# grouped result instead of extending the chain, as in Python. The
# marker is unwrapped by ``_eval`` and ``_visit``; every other node is
# safe to splice in directly (re-grouping ``and``/``or`` operands does
# not change their result).
if inner[0] == "chain":
return ("group", inner)
return inner

def list_body(self, *items: Any) -> tuple[Any, ...]:
Expand All @@ -228,7 +238,14 @@ def filtered(self, head: Any, filt: Any) -> tuple[str, Any, tuple[Any, ...]]:
return ("pipe", head, (filt,))

def cmp(self, left: Any, op: Token, right: Any) -> tuple[str, ...]:
return ("cmp", " ".join(str(op).split()), left, right)
# As for ``filtered`` and ``and_op``/``or_op``: the grammar nests a
# chain to the left; flatten it into one node so ``a < b < c`` keeps
# all its operands and operators side by side. ``("group", chain)``
# does not flatten, so a parenthesized comparison is one operand.
op_text = " ".join(str(op).split())
if left[0] == "chain":
return ("chain", left[1] + (right,), left[2] + (op_text,))
return ("chain", (left, right), (op_text,))

def or_op(self, left: Any, _op: Token, right: Any) -> tuple[str, tuple[Any, ...]]:
# As for ``filtered``: the grammar nests a chain to the left; flatten it
Expand Down Expand Up @@ -399,6 +416,19 @@ def _apply_filter(
)


def _compare_pair(left: Any, right: Any, op: str) -> bool:
"""One comparison of a chain, with the shared operator semantics."""
if op == "==":
return _safe_equals(left, right, negate=False)
if op == "!=":
return _safe_equals(left, right, negate=True)
if op == "in":
return _safe_membership(left, right, negate=False)
if op == "not in":
return _safe_membership(left, right, negate=True)
return _safe_compare(left, right, op)


def _eval(node: Any, namespace_: dict[str, Any]) -> Any:
"""Evaluate a tuple AST node against *namespace_*."""
tag = node[0]
Expand Down Expand Up @@ -426,19 +456,23 @@ def _eval(node: Any, namespace_: dict[str, Any]) -> Any:
if tag == "not":
return not bool(_eval(node[1], namespace_))

if tag == "cmp":
op = node[1]
left = _eval(node[2], namespace_)
right = _eval(node[3], namespace_)
if op == "==":
return _safe_equals(left, right, negate=False)
if op == "!=":
return _safe_equals(left, right, negate=True)
if op == "in":
return _safe_membership(left, right, negate=False)
if op == "not in":
return _safe_membership(left, right, negate=True)
return _safe_compare(left, right, op)
if tag == "group":
return _eval(node[1], namespace_)

if tag == "chain":
# Python/Jinja2 chained-comparison semantics: ``a < b < c`` is
# ``a < b and b < c`` with ``b`` evaluated once, left to right,
# stopping at the first false pair, so a later operand is only
# evaluated when every pair before it held. Validation walks the
# parse tree instead, so it still visits every operand.
operands, ops = node[1], node[2]
left = _eval(operands[0], namespace_)
for op, operand in zip(ops, operands[1:]):
right = _eval(operand, namespace_)
if not _compare_pair(left, right, op):
return False
left = right
return True

if tag in ("and", "or"):
# Left to right, stopping at the first operand that decides the result,
Expand Down Expand Up @@ -551,9 +585,11 @@ def _visit(node: Any, paths: list[str] | None = None, filters: list[Any] | None
elif tag in ("and", "or"):
for operand in node[1]:
_visit(operand, paths, filters)
elif tag == "cmp":
_visit(node[2], paths, filters)
_visit(node[3], paths, filters)
elif tag == "group":
_visit(node[1], paths, filters)
elif tag == "chain":
for operand in node[1]:
_visit(operand, paths, filters)
Comment thread
aarjang marked this conversation as resolved.
Resolved


def _collect_leaves(text: str) -> list[str]:
Expand Down
110 changes: 83 additions & 27 deletions tests/test_workflows.py
Original file line number Diff line number Diff line change
Expand Up @@ -1762,45 +1762,101 @@ def test_boolean_precedence_without_parentheses(self):
# Explicit grouping overrides the default and flips the result.
assert evaluate_expression("{{ (inputs.a or inputs.b) and inputs.c }}", ctx) is False

def test_comparisons_share_one_level_and_group_left_to_right(self):
"""No comparison operator has priority over another.

The former engine's operator scan order made ``==``/``!=`` bind looser
than ``<``/``>``/``in`` and grouped repeated comparisons from the right.
The grammar puts every comparison on one level, left-associative, so
``a == b > 0`` is ``(a == b) > 0``. Each case is checked against its
explicit grouping and against the other grouping, which gives a
different result, so the assertion fails if the precedence moves.
def test_comparisons_chain_like_python(self):
"""Comparisons share one level and chain as in Python and Jinja2 (#5071).

``a OP b OP c`` means ``a OP b and b OP c`` with the shared operand
evaluated once -- not ``(a OP b) OP c``. The former left-to-right
grouping compared a boolean with the next operand, so the range check
``0 <= inputs.n <= 10`` answered True for ``n = 50`` and an
``if``/``while`` step silently took the wrong branch. Every case is
asserted against Python's own result for the same expression.
"""
from specify_cli.workflows.expressions import evaluate_expression
from specify_cli.workflows.base import StepContext

ctx = StepContext(
inputs={"enabled": True, "count": 5, "mode": "x", "tags": ["x"]}
)
cases = [
("inputs.enabled == inputs.count > 0",
"(inputs.enabled == inputs.count) > 0",
"inputs.enabled == (inputs.count > 0)"),
("true == inputs.mode in inputs.tags",
"(true == inputs.mode) in inputs.tags",
"true == (inputs.mode in inputs.tags)"),
("inputs.enabled != inputs.count >= 10",
"(inputs.enabled != inputs.count) >= 10",
"inputs.enabled != (inputs.count >= 10)"),
("1 < 2 < 3", "(1 < 2) < 3", "1 < (2 < 3)"),
("3 > 2 > 1", "(3 > 2) > 1", "3 > (2 > 1)"),
inputs={"n": 50, "m": 5, "enabled": True, "count": 5,
"mode": "x", "tags": ["x"]}
)
chained = [
# The #5071 repro: out of range must be False.
("0 <= inputs.n <= 10", 0 <= 50 <= 10),
("0 <= inputs.m <= 10", 0 <= 5 <= 10),
("1 < 2 < 3", 1 < 2 < 3),
("3 > 2 > 1", 3 > 2 > 1),
("1 < 2 > 1", 1 < 2 > 1),
("'a' < 'b' < 'c'", "a" < "b" < "c"),
("inputs.count == 5 == 5", 5 == 5 == 5),
# Mixed operators chain pairwise instead of comparing a boolean.
("inputs.enabled == inputs.count > 0", True == 5 > 0),
("inputs.enabled != inputs.count >= 10", True != 5 >= 10),
("true == inputs.mode in inputs.tags", True == "x" in ["x"]),
# Four operands, three pairs.
("1 <= 1 == 1 != 2", 1 <= 1 == 1 != 2),
]
for plain, left, right in cases:
result = evaluate_expression("{{ " + plain + " }}", ctx)
assert result == evaluate_expression("{{ " + left + " }}", ctx), plain
assert result != evaluate_expression("{{ " + right + " }}", ctx), plain
for expr, want in chained:
assert evaluate_expression("{{ " + expr + " }}", ctx) is want, expr
# A chain is its explicit and-form.
assert evaluate_expression(
"{{ 0 <= inputs.n <= 10 }}", ctx
) == evaluate_expression("{{ 0 <= inputs.n and inputs.n <= 10 }}", ctx)
# Explicit parentheses end a chain, exactly as in Python: the grouped
# boolean is the operand of the next comparison.
assert evaluate_expression(
"{{ (0 <= inputs.n) <= 10 }}", ctx
) is ((0 <= 50) <= 10)
assert evaluate_expression("{{ 1 < (2 < 3) }}", ctx) is (1 < (2 < 3))
# Comparisons still bind tighter than not/and/or.
assert evaluate_expression("{{ not inputs.count > 9 }}", ctx) is True
assert evaluate_expression(
"{{ inputs.count > 9 or inputs.mode == 'x' }}", ctx
) is True

def test_chained_comparison_short_circuits_like_and(self):
"""A failing pair stops the chain before later operands run (#5071).

Mirrors the ``and`` guard: a later operand is evaluated only when
every pair before it held, so a chain can guard a filter that would
fail on an empty or invalid value. When the operand is reached, its
errors still fail the run.
"""
from specify_cli.workflows.expressions import evaluate_expression
from specify_cli.workflows.base import StepContext

ctx = StepContext(inputs={"payload": "not json", "n": 0})
# 5 <= 0 fails first, so the raising filter operand is never reached.
assert evaluate_expression(
"{{ 5 <= inputs.n <= (inputs.payload | from_json | length) }}", ctx
) is False
# A reached operand still raises.
with pytest.raises(ValueError, match="from_json"):
evaluate_expression(
"{{ 0 <= inputs.n <= (inputs.payload | from_json | length) }}",
ctx,
)

def test_chained_comparison_evaluates_the_shared_operand_once(self, monkeypatch):
"""``a <= b <= c`` resolves ``b`` once, as Python does (#5071).

The explicit and-form resolves it twice; the chain must not.
"""
import specify_cli.workflows.expressions.engine as engine_mod
from specify_cli.workflows.expressions import evaluate_expression
from specify_cli.workflows.base import StepContext

calls: list[str] = []
real = engine_mod._resolve_dot_path

def counting(namespace_, path):
calls.append(path)
return real(namespace_, path)

monkeypatch.setattr(engine_mod, "_resolve_dot_path", counting)
ctx = StepContext(inputs={"m": 5})
assert evaluate_expression("{{ 0 <= inputs.m <= 10 }}", ctx) is True
assert calls.count("inputs.m") == 1

def test_number_literal_forms(self):
"""Every number form the former engine read through ``int()``/``float()``.

Expand Down
21 changes: 21 additions & 0 deletions tests/unit/test_condition_expression_block.py
Original file line number Diff line number Diff line change
Expand Up @@ -1007,6 +1007,27 @@ def test_both_sides_of_a_boolean_are_reported():
assert _unresolvable_term("false and bogus") is not None


def test_every_operand_of_a_comparison_chain_is_reported():
"""Validation visits chain operands that runtime may skip (#5071).

A chained comparison short-circuits at the first false pair, like
``and``; the diagnostics walk the parse tree instead, so the final
operand's name and a misused filter in a later operand are still
reported -- including inside a parenthesized comparison, which ends the
chain for evaluation but stays transparent to the walk.
"""
chain = "5 <= inputs.n <= bogus"
assert _collect_leaves(chain) == ["inputs.n", "bogus"]
assert _unresolvable_term(chain) is not None
assert _evaluator_rejects("0 <= inputs.n <= (inputs.x | nosuchfilter)") is not None
assert _evaluator_rejects(
"(inputs.a < (inputs.x | nosuchfilter)) < inputs.b"
) is not None
assert _evaluator_rejects("0 <= inputs.n <= (inputs.items | length)") is None
grouped = "(1 < inputs.a) < inputs.b"
assert _collect_leaves(grouped) == ["inputs.a", "inputs.b"]


def test_a_long_boolean_chain_is_validated_without_exhausting_the_stack():
"""Validation walks every operand of a long chain, the last one included."""
chain = " or ".join(["inputs.flag"] * 1000)
Expand Down
Loading