Skip to content

Commit 68f5f24

Browse files
author
Markus
committed
refactor: split workflow expression evaluator into a package
Move src/specify_cli/workflows/expressions.py (1571 lines) into a layered package so the evaluator, its shared leaves, the public API and the condition diagnostics are separately testable and a future engine can be swapped at a single point (engine.py). Behaviour is unchanged. Layout: - namespace/operators/filters/template: shared leaves, no internal deps - engine_current: the hand-written evaluator, interpolation and probe helpers - engine: the selection point, re-exporting the full engine contract - api: evaluate_expression / evaluate_condition - diagnostics: condition validation and remediation - __init__: logic-free facade keeping the historical public surface and the test-only private names importable The two drift-guard tests keep their assertions; only the monkeypatch target moves to the module that owns the global (namespace / engine_current). A new boundary test asserts that no module but engine.py and the facade imports an engine implementation (engine_*). Verified in the harness worktree against the S3 corpus: current backend 7/7 required, 78/78 compat expression, 11/11 compat condition. Assisted-by: opencode (model: deepseek-v4.1-flash, supervised)
1 parent 0443760 commit 68f5f24

12 files changed

Lines changed: 1861 additions & 1573 deletions

File tree

‎src/specify_cli/workflows/expressions.py‎

Lines changed: 0 additions & 1571 deletions
This file was deleted.
Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
"""Sandboxed expression evaluator for workflow templates.
2+
3+
Provides a safe Jinja2 subset for evaluating expressions in workflow YAML.
4+
Templates cannot perform file I/O, import modules, or run arbitrary code —
5+
the evaluator only walks the namespace and applies a fixed set of filters.
6+
7+
This package is split by responsibility:
8+
9+
- ``namespace``/``filters``/``operators``/``template`` — shared leaves;
10+
- ``engine_current`` — the hand-written evaluator behind the contract;
11+
- ``engine`` — the selection point (the one line that swaps the engine);
12+
- ``api`` — the public evaluation entry points;
13+
- ``diagnostics`` — condition validation and remediation.
14+
15+
This ``__init__`` is a logic-free facade that keeps the historical
16+
``specify_cli.workflows.expressions`` surface — including the private names the
17+
tests import — working unchanged.
18+
"""
19+
20+
from __future__ import annotations
21+
22+
from .api import evaluate_condition, evaluate_expression
23+
from .diagnostics import (
24+
condition_has_malformed_expression_block,
25+
condition_is_interpolated_to_text,
26+
condition_is_never_evaluated,
27+
format_condition_correction,
28+
format_condition_remediation,
29+
_has_unbalanced_bracket,
30+
_has_unbalanced_quote,
31+
_unresolvable_term,
32+
)
33+
from .engine import (
34+
_COMPARISON_OPERATORS,
35+
_WORD_OPERATORS,
36+
_collect_leaves,
37+
_evaluator_rejects,
38+
_has_incomplete_operand,
39+
_leaf_sink,
40+
)
41+
from .filters import _REGISTERED_FILTERS
42+
from .template import _strip_stray_delimiters
43+
44+
__all__ = [
45+
"condition_has_malformed_expression_block",
46+
"condition_is_interpolated_to_text",
47+
"condition_is_never_evaluated",
48+
"evaluate_condition",
49+
"evaluate_expression",
50+
"format_condition_correction",
51+
"format_condition_remediation",
52+
"_COMPARISON_OPERATORS",
53+
"_REGISTERED_FILTERS",
54+
"_WORD_OPERATORS",
55+
"_collect_leaves",
56+
"_evaluator_rejects",
57+
"_has_incomplete_operand",
58+
"_has_unbalanced_bracket",
59+
"_has_unbalanced_quote",
60+
"_leaf_sink",
61+
"_strip_stray_delimiters",
62+
"_unresolvable_term",
63+
]
Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
"""Public evaluation API for workflow expression templates.
2+
3+
The API layer owns namespace construction and nothing else: the whole
4+
single-expression-vs-interpolation decision lives in the engine contract
5+
(``_evaluate_template``), reached only through ``engine.py``.
6+
"""
7+
8+
from __future__ import annotations
9+
10+
from typing import Any
11+
12+
from .engine import _evaluate_template
13+
from .namespace import _build_namespace
14+
15+
16+
def evaluate_expression(template: str, context: Any) -> Any:
17+
"""Evaluate a template string with ``{{ ... }}`` expressions.
18+
19+
If the entire string is a single expression, returns the raw value
20+
(preserving type). Otherwise, substitutes each expression inline
21+
and returns a string.
22+
23+
Parameters
24+
----------
25+
template:
26+
The template string (e.g., ``"{{ steps.plan.output.task_count }}"``
27+
or ``"Processed {{ inputs.spec }}"``.
28+
context:
29+
A ``StepContext`` or compatible object.
30+
31+
Returns
32+
-------
33+
The resolved value (any type for single-expression templates,
34+
string for multi-expression or mixed templates).
35+
"""
36+
if not isinstance(template, str):
37+
return template
38+
39+
namespace = _build_namespace(context)
40+
return _evaluate_template(template, namespace)
41+
42+
43+
def evaluate_condition(condition: str, context: Any) -> bool:
44+
"""Evaluate a condition expression and return a boolean.
45+
46+
Convenience wrapper around ``evaluate_expression`` that coerces
47+
the result to bool.
48+
"""
49+
result = evaluate_expression(condition, context)
50+
# Treat plain "false"/"true" strings as booleans so that
51+
# condition: "false" (without {{ }}) behaves as expected.
52+
#
53+
# Strip before matching: the string a condition resolves to is most often
54+
# captured command output, and a ``shell`` step stores ``proc.stdout``
55+
# verbatim, so ``run: echo false`` resolves to ``"false\n"``. Without the
56+
# strip that trailing newline matches neither branch and falls through to
57+
# ``bool("false\n")`` -> True, silently taking an ``if`` step's ``then``
58+
# branch (and keeping a ``while``/``do-while`` looping) on a step that
59+
# printed "false". A workflow cannot strip it itself -- no registered
60+
# filter trims whitespace (there is no ``trim``).
61+
# ``InitStep._resolve_bool`` and the catalog readers already strip before
62+
# matching boolean text. ``bool(result)`` below still sees the raw string,
63+
# so no non-boolean text changes truthiness.
64+
if isinstance(result, str):
65+
lower = result.strip().lower()
66+
if lower == "false":
67+
return False
68+
if lower == "true":
69+
return True
70+
return bool(result)

0 commit comments

Comments
 (0)