Skip to content

Commit 935fefb

Browse files
committed
feat: runner-evaluated let bindings with embedded-file ordering
Move EXPR `let` binding evaluation (RFC 0007) from the Session's action entry points into the script runners, mirroring openjd-rs's runner ordering: embedded-file *paths* are allocated first (a filename is a plain string, so allocation cannot depend on `let`), then the script's bindings evaluate — so they can reference Env.File.*/Task.File.* — and file *contents* are written after, so `data` expressions can use let-bound values. With the companion openjd-model and openjd-cli changes, the Python CLI passes the full openjd-specifications conformance suite (1145/1145), matching the Rust CLI. - EmbeddedFiles.materialize is split into allocate_file_paths and write_file_contents; the Env.File.*/Task.File.* symbols are typed as host-format paths for EXPR evaluation (property access like `.parent`/`.stem` works), matching openjd-rs. - The shared apply_let_bindings helper lives in _runner_base; the step/environment runners evaluate their script's bindings between the two phases. The Session's wrap-interception branches evaluate the wrapped script's bindings themselves before resolving the wrapped action (embedded files are not materialized on the wrap path). - An environment's `variables` resolve against the session symbol table without the script's own bindings, matching the openjd-rs runtime. - enter_environment gains extra_let_bindings: a step's environments are entered with the step-level bindings (Step.let on the instantiated Job) so their variables and actions can reference them — the v0 counterpart of the per-step resolved symbol table that openjd-rs threads into enter_environment. The bindings are re-applied when the environment exits so onExit resolves in the same scope. The unit suite passes (639 passed; the two known-flaky timer tests in test_runner_base.py pass serially), and mypy/black/ruff are clean. Signed-off-by: David Leong <116610336+leongdl@users.noreply.github.com>
1 parent ce06fa8 commit 935fefb

5 files changed

Lines changed: 200 additions & 91 deletions

File tree

‎src/openjd/sessions/_embedded_files.py‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -209,6 +209,23 @@ def __init__(
209209
self._user = user
210210

211211
def materialize(self, files: EmbeddedFilesListType, symtab: SymbolTable) -> None:
212+
records = self.allocate_file_paths(files, symtab)
213+
self.write_file_contents(records, symtab)
214+
215+
def allocate_file_paths(
216+
self, files: EmbeddedFilesListType, symtab: SymbolTable
217+
) -> list[_FileRecord]:
218+
"""Allocate the on-disk paths for the embedded files and define their
219+
``Env.File.*``/``Task.File.*`` symbols in ``symtab``, without writing
220+
the file contents.
221+
222+
Splitting allocation from :meth:`write_file_contents` lets the runner
223+
evaluate EXPR ``let`` bindings between the two phases (RFC 0007): a
224+
file's *path* never depends on ``let`` values (``filename`` is a plain
225+
string), so the ``Env.File.*``/``Task.File.*`` symbols are available
226+
to the bindings, while a file's ``data`` is written afterwards so it
227+
can reference let-bound values. Mirrors the openjd-rs runners.
228+
"""
212229
if self._scope == EmbeddedFilesScope.ENV:
213230
self._logger.info("Writing embedded files for Environment to disk.")
214231
else:
@@ -222,17 +239,28 @@ def materialize(self, files: EmbeddedFilesListType, symtab: SymbolTable) -> None
222239
symbol, filename = self._get_symtab_entry(file)
223240
records.append(_FileRecord(symbol=symbol, filename=filename, file=file))
224241

225-
# Add symbols to the symbol table
242+
# Add symbols to the symbol table. For EXPR evaluation the
243+
# Env.File.*/Task.File.* symbols are host-format path values
244+
# (property access like `.parent` works), matching openjd-rs;
245+
# the legacy (non-EXPR) interpolation path ignores the type and
246+
# keeps the string form.
226247
for record in records:
227248
symtab[record.symbol] = str(record.filename)
249+
symtab.expr_types[record.symbol] = "PATH"
228250
self._logger.info(
229251
f"Mapping: {record.symbol} -> {record.filename}",
230252
extra=LogExtraInfo(
231253
openjd_log_content=LogContent.FILE_PATH | LogContent.PARAMETER_INFO
232254
),
233255
)
256+
return records
257+
except (OSError, ValueError) as err:
258+
raise RuntimeError(f"Could not write embedded file: {err}")
234259

235-
# Write the files to disk.
260+
def write_file_contents(self, records: list["_FileRecord"], symtab: SymbolTable) -> None:
261+
"""Resolve each allocated file's ``data`` against ``symtab`` and write
262+
it to disk. See :meth:`allocate_file_paths`."""
263+
try:
236264
for record in records:
237265
# Raises: OSError
238266
self._materialize_file(record.filename, record.file, symtab)

‎src/openjd/sessions/_runner_base.py‎

Lines changed: 76 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,10 @@
1818
from openjd.model import SymbolTable
1919
from openjd.model import FormatStringError
2020
from openjd.model.v2023_09 import Action as Action_2023_09
21+
from openjd.model.v2023_09 import ArgString as ArgString_2023_09
2122
from openjd.model.v2023_09 import CancelationMethodDeferred as CancelationMethodDeferred_2023_09
2223
from openjd.model.v2023_09 import CancelationMode as CancelationMode_2023_09
24+
from openjd.model.v2023_09 import ModelParsingContext as ModelParsingContext_2023_09
2325
from ._embedded_files import EmbeddedFiles, EmbeddedFilesScope, write_file_for_user
2426
from ._logging import log_subsection_banner, LoggerAdapter, LogContent, LogExtraInfo
2527
from ._os_checker import is_posix
@@ -34,6 +36,7 @@
3436
"TerminateCancelMethod",
3537
"NotifyCancelMethod",
3638
"ScriptRunnerBase",
39+
"apply_let_bindings",
3740
)
3841

3942

@@ -196,6 +199,47 @@ def resolve_period(period: Any) -> Optional[int]:
196199
)
197200

198201

202+
def apply_let_bindings(*, symtab: SymbolTable, let_bindings: list[str]) -> None:
203+
"""Evaluate EXPR ``let`` bindings (RFC 0007) and add them to ``symtab``.
204+
205+
``let_bindings`` is a script's ``let`` field: an ordered list of
206+
``"name = expression"`` strings. Each RHS is an EXPR expression evaluated
207+
against the symbol table built so far (so later bindings can reference
208+
earlier ones), and the engine's typed result is stored under the bound
209+
name — a let-bound path stays a path for property access, and float
210+
rendering fidelity is preserved — matching the Rust runtime's natively
211+
typed symbol table.
212+
213+
The runners evaluate bindings after embedded-file *path* allocation and
214+
before file *contents* are written, so a binding may reference
215+
``Env.File.*``/``Task.File.*`` and a file's ``data`` may reference
216+
let-bound values (mirroring openjd-rs's runner ordering).
217+
218+
Raises:
219+
ValueError (FormatStringError/ExpressionError): if a binding's
220+
expression cannot be evaluated.
221+
"""
222+
# `let` only appears under the EXPR extension; force it on for parsing
223+
# the RHS regardless of the session's configured extension set.
224+
context = ModelParsingContext_2023_09(supported_extensions=["EXPR"])
225+
226+
for binding in let_bindings:
227+
name, sep, rhs = binding.partition("=")
228+
name = name.strip()
229+
rhs = rhs.strip()
230+
if not sep or not name or not rhs:
231+
# Malformed bindings are rejected by the model's `let` validator
232+
# at decode time; skip defensively here.
233+
continue
234+
# Parse the RHS as a standalone EXPR expression and evaluate it
235+
# against the current symbol table.
236+
arg = ArgString_2023_09("{{ " + rhs + " }}", context=context)
237+
expressions = arg.expressions
238+
if not expressions or expressions[0].expression is None:
239+
continue
240+
symtab[name] = expressions[0].expression.evaluate_value(symtab=symtab)
241+
242+
199243
class ScriptRunnerBase(ABC):
200244
"""Base class for a runnable Environment or Step Script.
201245
Responsible for running a *single* Action, and optionally canceling it.
@@ -504,10 +548,17 @@ def _materialize_files(
504548
files: EmbeddedFilesListType,
505549
dest_directory: Path,
506550
symtab: SymbolTable,
551+
let_bindings: Optional[list[str]] = None,
507552
) -> None:
508553
"""Helper for derived classes that wraps all of the logic around
509554
materializing embedded files to disk.
510555
556+
When ``let_bindings`` is given, they are evaluated between file-path
557+
allocation and content writing (RFC 0007, mirroring the openjd-rs
558+
runners): a file's *path* never depends on ``let`` values (filenames
559+
are plain strings), so ``Env.File.*``/``Task.File.*`` are available to
560+
the bindings, while a file's ``data`` is written afterwards so it can
561+
reference let-bound values.
511562
"""
512563
file_writer = EmbeddedFiles(
513564
logger=self._logger,
@@ -516,10 +567,14 @@ def _materialize_files(
516567
user=self._user,
517568
)
518569
try:
519-
file_writer.materialize(files, symtab)
520-
except RuntimeError as exc:
521-
# Had a problem writing at least one file to disk.
522-
# Surface the error.
570+
records = file_writer.allocate_file_paths(files, symtab)
571+
if let_bindings:
572+
apply_let_bindings(symtab=symtab, let_bindings=let_bindings)
573+
file_writer.write_file_contents(records, symtab)
574+
except (RuntimeError, ValueError) as exc:
575+
# Had a problem writing at least one file to disk, or evaluating
576+
# a `let` binding (FormatStringError/ExpressionError subclass
577+
# ValueError). Surface the error.
523578
# Make use of the action filter to surface the failure reason to
524579
# the customer.
525580
self._logger.info(
@@ -532,6 +587,23 @@ def _materialize_files(
532587
if self._callback is not None:
533588
self._callback(ActionState.FAILED)
534589

590+
def _apply_let_bindings_or_fail(self, symtab: SymbolTable, let_bindings: list[str]) -> bool:
591+
"""Evaluate the script's EXPR ``let`` bindings into ``symtab``. On an
592+
evaluation error the action is failed through the normal failure path
593+
(openjd_fail log, FAILED state, callback). Returns True on success."""
594+
try:
595+
apply_let_bindings(symtab=symtab, let_bindings=let_bindings)
596+
except ValueError as exc:
597+
self._logger.info(
598+
f"openjd_fail: {str(exc)}",
599+
extra=LogExtraInfo(openjd_log_content=LogContent.EXCEPTION_INFO),
600+
)
601+
self._state_override = ScriptRunnerState.FAILED
602+
if self._callback is not None:
603+
self._callback(ActionState.FAILED)
604+
return False
605+
return True
606+
535607
def _run_action(
536608
self,
537609
action: ActionModel,

‎src/openjd/sessions/_runner_env_script.py‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,15 @@ def _run_env_action(
123123

124124
log_subsection_banner(self._logger, "Phase: Setup")
125125

126-
# Write any embedded files to disk
126+
let_bindings = (
127+
getattr(self._environment_script, "let", None)
128+
if self._environment_script is not None
129+
else None
130+
)
131+
# Write any embedded files to disk. File paths are allocated before
132+
# the script's EXPR `let` bindings evaluate (so bindings can reference
133+
# Env.File.*), and contents are written after (so `data` can reference
134+
# let-bound values) — mirroring the openjd-rs runner.
127135
if (
128136
self._environment_script is not None
129137
and self._environment_script.embeddedFiles is not None
@@ -135,9 +143,14 @@ def _run_env_action(
135143
self._environment_script.embeddedFiles,
136144
self._session_files_directory,
137145
symtab,
146+
let_bindings=let_bindings,
138147
)
139148
if self.state == ScriptRunnerState.FAILED:
140149
return
150+
elif let_bindings:
151+
symtab = SymbolTable(source=self._symtab)
152+
if not self._apply_let_bindings_or_fail(symtab, let_bindings):
153+
return
141154
else:
142155
symtab = self._symtab
143156

‎src/openjd/sessions/_runner_step_script.py‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,17 +102,26 @@ def run(self) -> None:
102102

103103
# For the type checker.
104104
assert isinstance(self._script, StepScript_2023_09)
105-
# Write any embedded files to disk
105+
let_bindings = getattr(self._script, "let", None)
106+
# Write any embedded files to disk. File paths are allocated before
107+
# the script's EXPR `let` bindings evaluate (so bindings can reference
108+
# Task.File.*), and contents are written after (so `data` can
109+
# reference let-bound values) — mirroring the openjd-rs runner.
106110
if self._script.embeddedFiles is not None:
107111
symtab = SymbolTable(source=self._symtab)
108112
self._materialize_files(
109113
EmbeddedFilesScope.STEP,
110114
self._script.embeddedFiles,
111115
self._session_files_directory,
112116
symtab,
117+
let_bindings=let_bindings,
113118
)
114119
if self.state == ScriptRunnerState.FAILED:
115120
return
121+
elif let_bindings:
122+
symtab = SymbolTable(source=self._symtab)
123+
if not self._apply_let_bindings_or_fail(symtab, let_bindings):
124+
return
116125
else:
117126
symtab = self._symtab
118127

0 commit comments

Comments
 (0)