Skip to content

Commit 09c26e2

Browse files
markuswondrakMarkusCopilot
authored andcommitted
feat(workflows): parse workflow expressions with a Lark LALR grammar (github#5171)
* refactor: derive filter metadata from one table and add a syntax-error hook Preparation for a grammar-based engine; behavior-neutral for the hand-written engine. - filters.py: FILTER_TABLE (function, argument form, usage text) is the single source; _REGISTERED_FILTERS, _ZERO_ARG_FILTERS and the "expected one of ..." message are derived from it. The message text is byte-identical to the previous literal in engine_current. - engine contract: _syntax_error(text) returns a parse-error message or None. engine_current has no syntax layer and always returns None. - diagnostics.py: prefers _syntax_error over the leaf walk in _unresolvable_term and after the incomplete-operand check in _wrapping_would_not_repair, so a parser's message (with position) reaches the condition diagnostics. No test changes; 1150 passed in the expression and condition test files. Assisted-by: OpenCode (model: claude-opus-5.5, autonomous) * feat(workflows): parse workflow expressions with a Lark LALR grammar Replace the hand-written block-body parser with a Lark (LALR) grammar and select it in engine.py. The expression language is unchanged (github#5060). - LALR parser with keyword terminal priority. - The ambiguous-precedence guards are a grammar property: a filter chain only applies to an operator-free head, so a pipe after a comparison or after `not` is a parse error ("ambiguous filter precedence"). - The PATH terminal is built from namespace._PLAIN_SEGMENT / _INDEXED_SEGMENT, so path syntax has one definition; the existing drift test now covers the grammar too. - _collect_leaves / _evaluator_rejects are a single static tree walk; the probe run and _leaf_sink are gone from the contract. - _syntax_error returns the parser's message with column, which the condition diagnostics use. - Filters dispatch through FILTER_TABLE. Deliberate test changes, each with its reason in the test: - [1,2,3][1] and an unclosed quote in a condition raise ValueError instead of silently yielding None / False. - Trailing tokens after a filter name, and a comparison after a filter chain, are parse errors ("invalid expression") instead of dispatcher messages; still ValueError. - Three diagnostics fixture rows expect the parser's message. - The probe-only tests are replaced (leaf-walk transparency of groups) or removed (_leaf_sink); imports of engine internals are dropped. Assisted-by: OpenCode (model: claude-opus-5.5, autonomous) Assisted-by: GitHub Copilot CLI (model: Claude Sonnet 5.5, supervised) Co-authored-by: Copilot <[email protected]> * fix(workflows): short-circuit and/or in the Lark expression engine The Lark engine evaluated both operands of `and`/`or`, which regressed the behavior added in github#4923: a guard such as `inputs.payload != '' and (inputs.payload | from_json | length)` ran `from_json` on an empty string again. Return as soon as the left operand decides the result. Validation walks the parse tree, so skipped operands are still checked there. Assisted-by: GitHub Copilot CLI (model: Claude Sonnet 5.5, supervised) Co-authored-by: Copilot <[email protected]> * refactor(workflows): remove the hand-written expression engine The Lark engine is the only engine behind engine.py, so delete engine_current.py and everything that only it used: the `_leaf_sink` export, `_split_top_level_commas`, `_is_single_list_literal`, `_is_wrapped_in_parens`, `_EXPR_PATTERN` and `_ZERO_ARG_FILTERS`. Rename engine_lark_a2 to engine_lark, pin `lark>=1.3.1,<2.0.0`, and drop the prototype wording from docstrings and test comments. Assisted-by: GitHub Copilot CLI (model: Claude Sonnet 5.5, supervised) Co-authored-by: Copilot <[email protected]> * fix(workflows): restore expression forms and messages lost in the Lark engine Review of the Lark engine against the former hand-written engine found inputs that now fail or report the wrong problem: - Number literals accepted by int()/float() before (`.5`, `5.`, `+5`, `1_000`, `1.5e3`) failed to lex. `1e3` stays invalid, as before. - `a == not b` no longer parsed; `not` is accepted on the right of a comparison again and negates only its operand. - Filters evaluated their arguments before checking the call form, so a failing argument hid a misused or unknown filter. The documented order (form first) is restored. - Condition validation reported an operator after a filter chain (`items | length > 0`) as "missing an operand", and `a || b` as "ambiguous filter precedence". The parser's expected-token set now separates the two. Documented as deliberate and pinned by tests: - All comparison operators share one precedence level, left to right (`a == b > 0` is `(a == b) > 0`). The former engine's scan order gave them accidental priorities. - Prose in `{{ }}` and path keys outside `[\w-]` are syntax errors instead of a None lookup. Assisted-by: GitHub Copilot CLI (model: Claude Opus 5.5, autonomous) Co-authored-by: Copilot <[email protected]> * chore(deps): refresh security audit snapshot for lark Regenerated with the command documented in CONTRIBUTING.md so the dependency-audit job finds lark in the committed snapshot. The command upgrades, so a few unrelated pins moved to their latest patch releases. Assisted-by: GitHub Copilot (model: Claude Sonnet 5.5, autonomous) Co-authored-by: Copilot <[email protected]> * fix(workflows): name misplaced filter chains from the parse tree `inputs.mode not 'done'` was reported as an ambiguous filter precedence mistake although it has no filter. The message was inferred from the terminals the parser expected at the failure, and `|` is expected after any plain operand, not only after a filter chain. The grammar now parses `|` as a postfix operator that binds tightest, so a filter chain is a node wherever it appears. `_parse` refuses a tree in which an operator has such a node as a direct operand and names the leftmost one. Parentheses keep their group node, so `(items | length) > 0` stays valid. Accepted inputs and their ASTs are unchanged; malformed text without a misplaced chain now gets the plain positional syntax error. Assisted-by: GitHub Copilot (model: Claude Opus 5.5, autonomous) Co-authored-by: Copilot <[email protected]> * fix(workflows): name the operator in filter-precedence errors and correct validation docs The operator-first filter-precedence error now names the offending operator and suggests parenthesizing the filtered operand, matching the chain-first message. ARCHITECTURE.md no longer claims condition expressions are syntax-checked at validation time; validators check only delimiters and layout. Assisted-by: GitHub Copilot (model: Claude Sonnet 5.5, autonomous) Co-authored-by: Copilot <[email protected]> * refactor(workflows): fold engine_lark into engine and reject word operators as paths Move the Lark expression engine directly into engine.py now that engine_current.py is gone, and remove the temporary engine-swap boundary test. Exclude the reserved word operators (and, or, not, in) from the first segment of PATH so they never lex as variable names when an operand is expected, and include Lark's VisitError in _PARSE_ERRORS so int()/float() conversion errors in _BuildAst.number surface as ValueError. Assisted-by: Pi Coding Agent (model: gemini-4-argon, supervised) * docs(workflows): warn that path keys outside [\w-] no longer resolve The docs said the former engine looked up a key such as `{{ inputs.weird:key }}` as a path and rendered the miss as an empty string or `None`. When the key existed, the lookup resolved to its value, so a workflow that uses such a key worked before and now fails with a ValueError at run time. Correct the claim in workflows/ARCHITECTURE.md, the engine docstring and the test docstring, and add a compatibility note to the workflow reference: rename the key and its references, since quoted-key lookup is not supported and validation may not catch these expressions before a run. Assisted-by: Pi Coding Agent (model: claude-opus-5.5, autonomous) * test(workflows): pin the integer limit in the number-literal test The 5,000-digit literal was refused only because of Python's default limit on integer string conversion. With PYTHONINTMAXSTRDIGITS=0 the literal parses, and test_malformed_number_literals_are_refused failed. Move the case into its own test, which sets a known limit and restores the previous one. Assisted-by: Pi Coding Agent (model: claude-opus-5.5, autonomous) * fix(workflows): evaluate long and/or chains without exhausting the stack The Lark engine built its AST with Lark's recursive Transformer, which uses about two Python frames per tree level, and nested `a or b or c` as `((a or b) or c)`. Building, evaluating and validating the tree all recursed once per operator, so a condition of about 500 terms or 500 nested parentheses raised RecursionError. That includes `true or ...`, which the former engine returned after its first operand, and the validation of a bare condition of that length, which raised instead of reporting the missing braces. Build the AST with Transformer_NonRecursive and flatten each and/or chain into one node, as filter chains already are. Evaluation loops over the operands and stops at the first one that decides the result; validation visits all of them. Chains and parentheses no longer depend on the recursion limit (tested to 5,000). `not` chains, comparison chains and nested lists keep the former engine's limit of about 1,000 levels. Assisted-by: Pi Coding Agent (model: claude-opus-5.5, autonomous) --------- Co-authored-by: Markus <[email protected]> Co-authored-by: Copilot <[email protected]>
1 parent 253fdb5 commit 09c26e2

13 files changed

Lines changed: 1279 additions & 981 deletions

File tree

‎.github/security-audit-requirements.txt‎

Lines changed: 161 additions & 153 deletions
Large diffs are not rendered by default.

‎docs/reference/workflows.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1280,7 +1280,7 @@ Notes on the newer filters:
12801280
- **`to_json` output is deterministic.** Object keys are sorted and non-ASCII characters are left as-is rather than escaped, so the same value always serializes to the same bytes. That buys reproducibility only — it does **not** make the result safe to pass through a shell, because [interpolation adds no quoting or escaping](#interpolation-and-shell-safety). Do not interpolate unconstrained JSON into a `run` field.
12811281
- **`to_json` rejects non-finite floats.** `NaN`, `Infinity`, and `-Infinity` raise a `ValueError` naming `to_json` instead of serializing to bare tokens. None of the three is valid JSON, so emitting them would hand a standards-compliant downstream parser a string it must reject.
12821282
- **`to_json` requires string mapping keys.** JSON objects have string keys, so a mapping with any other key type — `{1: "a"}`, `{True: "a"}` — raises a `ValueError` naming the key type instead. Left to `json.dumps`, an integer key would be coerced to `"1"` and collide with an existing `"1"` key, while mixed key types would fail `sort_keys` with an ordering `TypeError` reported only as "not JSON-serializable".
1283-
- **Comparing filtered counts requires parentheses.** The parser splits on the top-level `|` before looking for operators, so an unparenthesized trailing comparison such as `{{ inputs.items | length > 0 }}` raises a `ValueError`. Parenthesize the filtered operand to compare its result: `{{ (inputs.items | length) > 0 }}`. For a threshold of at least two:
1283+
- **Comparing filtered counts requires parentheses.** A filter chain cannot be an operand of an operator, so an unparenthesized trailing comparison such as `{{ inputs.items | length > 0 }}` raises an "ambiguous filter precedence" `ValueError`. Parenthesize the filtered operand to compare its result: `{{ (inputs.items | length) > 0 }}`. For a threshold of at least two:
12841284

12851285
```yaml
12861286
condition: "{{ (inputs.items | length) >= 2 }}"
@@ -1294,6 +1294,12 @@ Notes on the newer filters:
12941294

12951295
`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.
12961296

1297+
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`.
1298+
1299+
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`.
1300+
1301+
> **Compatibility:** Earlier releases could resolve an expression such as `{{ inputs.weird:key }}` when the key existed; this expression now fails at runtime. Rename keys you control (for example, `weird:key` to `weird_key`) and update their references. Quoted-key lookup is not supported. Workflow validation may not detect these expressions before execution.
1302+
12971303
Example:
12981304

12991305
```yaml

‎pyproject.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ dependencies = [
1515
"json5>=0.13.0",
1616
"mcp>=2.2.0,<3.0.0",
1717
"pydantic>=2.13.0,<3.0.0",
18+
"lark>=1.3.1,<2.0.0",
1819
]
1920

2021
[project.scripts]

‎src/specify_cli/workflows/expressions/__init__.py‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,7 @@
77
This package is split by responsibility:
88
99
- ``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);
10+
- ``engine`` — the Lark (LALR) expression parser and evaluator;
1211
- ``api`` — the public evaluation entry points;
1312
- ``diagnostics`` — condition validation and remediation.
1413
@@ -36,7 +35,6 @@
3635
_collect_leaves,
3736
_evaluator_rejects,
3837
_has_incomplete_operand,
39-
_leaf_sink,
4038
)
4139
from .filters import _REGISTERED_FILTERS
4240
from .template import _strip_stray_delimiters
@@ -57,7 +55,6 @@
5755
"_has_incomplete_operand",
5856
"_has_unbalanced_bracket",
5957
"_has_unbalanced_quote",
60-
"_leaf_sink",
6158
"_strip_stray_delimiters",
6259
"_unresolvable_term",
6360
]

‎src/specify_cli/workflows/expressions/diagnostics.py‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
_first_unclosable_block,
1919
_has_incomplete_operand,
2020
_is_single_expression,
21+
_syntax_error,
2122
)
2223
from .template import _split_top_level, _strip_stray_delimiters
2324

@@ -261,6 +262,15 @@ def _unresolvable_term(text: str) -> str | None:
261262
if not stripped:
262263
return "an operand is empty"
263264

265+
# A grammar-based engine can name the parse fault directly, position and
266+
# character included. Prefer that over the leaf walk: text that does not
267+
# parse has no leaves, and reporting "no unresolvable term" for it would
268+
# tell the author their expression is fine. ``None`` for the hand-written
269+
# engine, which resolves unknown shapes to ``None`` instead.
270+
syntax = _syntax_error(stripped)
271+
if syntax is not None:
272+
return syntax
273+
264274
for leaf in _collect_leaves(stripped):
265275
reason = _unresolvable_leaf(leaf)
266276
if reason is not None:
@@ -285,6 +295,13 @@ def _wrapping_would_not_repair(core: str) -> str | None:
285295
return "its brackets do not balance"
286296
if _has_incomplete_operand(core):
287297
return "an operator in it is missing an operand"
298+
# After the incomplete-operand check, not before: the four "missing an
299+
# operand" shapes are also parse failures, and the specific message is the
300+
# better one for them. Everything left that does not parse (arithmetic,
301+
# stray characters, a second literal) gets the engine's own message.
302+
syntax = _syntax_error(core)
303+
if syntax is not None:
304+
return syntax
288305
unresolvable = _unresolvable_term(core)
289306
if unresolvable is not None:
290307
return unresolvable

0 commit comments

Comments
 (0)