Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

14.8 KB
Raw Blame
"""Condition validation and remediation for workflow expressions.

These checks run at validation time and predict what the runtime evaluator will
do. They read the evaluator's own definitions through the ``engine`` contract
(and the shared scanners in ``template``), never a second copy of the grammar,
so a widened engine reaches the gate for free.
"""

from __future__ import annotations

import json
from typing import Any

from . import namespace
from .engine import (
    _collect_leaves,
    _evaluator_rejects,
    _first_unclosable_block,
    _has_incomplete_operand,
    _is_single_expression,
)
from .template import _split_top_level, _strip_stray_delimiters


def condition_is_never_evaluated(condition: Any) -> bool:
    """True when a string *condition* is silently treated as always-true text.

    ``evaluate_condition`` resolves its argument through
    ``evaluate_expression``, which only substitutes ``{{ ... }}`` blocks. A
    string with no such block comes back unchanged, and β€” unless it reads
    ``true``/``false`` β€” is then coerced by ``bool()``. So an expression
    authored without the braces, e.g. ``condition: inputs.count > 100``, is
    never evaluated at all: it is a non-empty string, so the ``if`` step always
    takes ``then`` and a ``while``/``do-while`` step always runs to
    ``max_iterations``.

    That is the same silent-truthiness authoring mistake the step validators
    already reject for a list/dict/number condition, and it is easy to write:
    GitHub Actions accepts a bare expression in ``if:``.

    The empty string is excluded β€” it coerces to ``False``, which is a definite
    answer rather than a silent always-true. Non-empty whitespace is *not*
    excluded: ``bool("   ")`` is true, and ``evaluate_condition`` strips only
    while testing the ``true``/``false`` keywords before falling through to
    ``bool()`` on the raw string. That runtime behaviour is pinned deliberately
    by ``test_condition_whitespace_only_string_stays_truthy``, so the authoring
    mistake has to be caught here instead: ``condition: "   "`` always takes
    ``then``.
    """
    if not isinstance(condition, str):
        return False
    if condition == "":
        return False
    stripped = condition.strip()
    if not stripped:
        return True
    if stripped.lower() in ("true", "false"):
        return False
    if "{{" not in stripped:
        return True
    # An opening ``{{`` the substituter cannot close is no better than a missing
    # one -- but only when the substituter really does leave it alone.
    # ``_interpolate_expressions`` has two sub-cases when its quote-aware scan
    # fails, and they do not behave alike: with no raw ``}}`` in the tail the
    # block is emitted verbatim (never evaluated, so ``bool()`` makes it true),
    # while a raw ``}}`` further along is used as the close and the truncated
    # body *is* evaluated. Only the first is "never evaluated"; see
    # ``condition_has_malformed_expression_block`` for the second.
    return _first_unclosable_block(stripped) == "verbatim"


def condition_is_interpolated_to_text(condition: Any) -> bool:
    """True when *condition* holds ``{{ }}`` blocks but is spliced into text, not evaluated.

    ``evaluate_expression`` takes its typed fast path only when the whole string is
    exactly one ``{{ ... }}`` block (``_is_single_expression``). Anything else β€” two
    blocks, or one block with any text around it β€” goes to ``_interpolate_expressions``,
    which substitutes each block into the surrounding string and returns a *string*.
    ``evaluate_condition`` then coerces that with ``bool()``, so the result is true for
    every rendering except ``""``, ``"true"`` and ``"false"``::

        {{ inputs.ready }} and {{ inputs.count > 100 }}   ->  "False and False"  ->  True
        not {{ inputs.ready }}                            ->  "not False"        ->  True
        {{ inputs.count }} > 100                          ->  "0 > 100"          ->  True

    Each of those reads as a real expression and is always true, which is the same
    silent-truthiness fault ``condition_is_never_evaluated`` reports one layer out: there
    the braces are missing, here they are present but do not cover the whole condition.
    The operators belong *inside* one block, and the validators already tell authors the
    condition must be "a single complete '{{ }}' block" -- this is the check behind that
    sentence.

    Deliberately derived from ``_is_single_expression`` rather than restated, so this
    cannot drift from the fast path it is predicting.
    """
    if not isinstance(condition, str):
        return False
    stripped = condition.strip()
    if not stripped or "{{" not in stripped:
        return False
    # Leave both of the faults that already have their own message and advice: a block
    # the substituter cannot close is not an interpolation problem.
    if condition_is_never_evaluated(condition) or condition_has_malformed_expression_block(condition):
        return False
    return not _is_single_expression(stripped)


def condition_has_malformed_expression_block(condition: Any) -> bool:
    """True when *condition* holds a ``{{`` block the quote-aware scan cannot close,
    but which ``_interpolate_expressions`` still evaluates through its raw-close
    fallback.

    This is a different fault from the one
    ``condition_is_never_evaluated`` reports, and it deserves a different message.
    The block is not skipped: the interpolator takes the first raw ``}}`` after the
    opener and evaluates whatever it truncated, so

        {{ inputs.missing | default('oops }}

    reaches ``_apply_filter`` and raises ``ValueError`` at run time. The truncation does
    not always raise -- ``{{ inputs.x == '}}'`` evaluates to the residual ``"False'"`` --
    but either way what runs is not what was written, so "never evaluated and always
    true" is the wrong report.

    Kept separate from the never-evaluated check rather than folded in, because the
    two need opposite advice: one says "you forgot the braces", this one says "your
    delimiters or quotes do not balance".
    """
    if not isinstance(condition, str):
        return False
    stripped = condition.strip()
    if not stripped or stripped.lower() in ("true", "false"):
        return False
    return _first_unclosable_block(stripped) == "evaluated"


def format_condition_correction(condition: Any) -> str:
    """Render *condition* wrapped in ``{{ }}`` as a quoted, paste-ready YAML scalar.

    The validators hand this back as the corrected form, so it has to survive a
    round trip through a YAML parser. A plain ``"{{ ... }}"`` does not: a
    condition holding a double quote (``inputs.name == "zzz"``) closes the
    scalar early and the workflow file no longer loads. Quoting is therefore
    chosen from the content. That enumeration was incomplete: a condition loaded
    from a YAML literal block can carry a newline, which a double-quoted scalar
    folds, so the correction did not round-trip.

    ``json.dumps`` decides it instead. Every JSON string is a valid YAML
    double-quoted scalar, and it escapes the quotes, backslashes, newlines and
    other control characters that hand-rolled quoting has to enumerate.
    ``ensure_ascii=False`` keeps non-ASCII operands readable rather than
    expanding them into numeric escapes.

    A stray delimiter is dropped rather than nested: ``{{ inputs.count > 100``
    corrects to ``"{{ inputs.count > 100 }}"``, not to a doubled ``{{ {{ ... }} }}``.
    Every stray delimiter goes, not only the ones sitting at the edges. Trimming
    just the edges left ``prefix {{ inputs.ready`` reading
    ``"{{ prefix {{ inputs.ready }}"`` -- an unclosed inner block, and one whose
    complete *outer* block then carried the correction straight back through
    ``condition_is_never_evaluated`` as if it were valid.
    """
    core = _strip_stray_delimiters(str(condition)).strip()
    # A blank core has nothing to wrap; render the empty block rather than the
    # double-spaced "{{  }}" that string concatenation would otherwise produce.
    body = "{{ " + core + " }}" if core else "{{ }}"
    return json.dumps(body, ensure_ascii=False)


def _has_unbalanced_quote(text: str) -> bool:
    """True when a quote opened in *text* is never closed.

    Same left-to-right, first-quote-wins scan the rest of this module uses, so the
    answer agrees with what ``_find_block_close`` and ``_strip_stray_delimiters``
    consider "inside a string".
    """
    quote: str | None = None
    for ch in text:
        if quote is not None:
            if ch == quote:
                quote = None
        elif ch in ("'", '"'):
            quote = ch
    return quote is not None


_BRACKET_PAIRS = {")": "(", "]": "[", "}": "{"}


def _has_unbalanced_bracket(text: str) -> bool:
    """True when brackets outside a quoted operand do not nest and match.

    A depth counter is not enough: it calls ``inputs.f(]`` balanced, because the
    ``]`` cancels the ``(``. The evaluator then resolves that body to ``None`` and
    the comparison is false, which is the inversion this module is trying to keep
    out of the suggested correction. Track the opener types instead.
    """
    stack: list[str] = []
    quote: str | None = None
    for ch in text:
        if quote is not None:
            if ch == quote:
                quote = None
        elif ch in ("'", '"'):
            quote = ch
        elif ch in "([{":
            stack.append(ch)
        elif ch in _BRACKET_PAIRS and (not stack or stack.pop() != _BRACKET_PAIRS[ch]):
            return True
    return bool(stack)


def _unresolvable_leaf(leaf: str) -> str | None:
    """Why the evaluator cannot resolve the name *leaf*, or ``None``.

    Namespace knowledge only. Everything about where operands live now comes from
    the evaluator itself, so nothing here restates the grammar.
    """
    segments = _split_top_level(leaf, ".")
    if not namespace._is_path_segment(segments[0].strip()):
        return f"{leaf!r} is not a name the evaluator can resolve"
    # `item` is the only root that is not always a mapping: `StepContext.item` is
    # `Any` and a fan-out assigns the item value itself, so when that value is a
    # list `_resolve_dot_path` indexes it and `item[0] == 'x'` resolves. Every
    # other root comes back from `_build_namespace` as a mapping, and the index
    # branch returns None for those however it is written -- so the index is
    # stripped for `item` alone rather than for roots in general.
    root = segments[0].strip()
    # Read the module attribute, not an imported copy: the wiring test widens
    # `namespace._INDEXED_SEGMENT` and expects this check to follow.
    indexed_root = namespace._INDEXED_SEGMENT.match(root)
    if indexed_root is not None and indexed_root.group(1) == "item":
        root = indexed_root.group(1)
    if root not in namespace._NAMESPACE_ROOTS:
        return (
            f"{segments[0].strip()!r} is not one of the namespace roots "
            f"({', '.join(namespace._NAMESPACE_ROOTS)})"
        )
    for segment in segments[1:]:
        if not namespace._is_path_segment(segment.strip()):
            return f"{segment.strip()!r} is not a valid path segment"
    return None


def _unresolvable_term(text: str) -> str | None:
    """The first name in *text* the evaluator cannot resolve, or ``None``.

    Asks the evaluator which names it will look up, then applies the namespace
    rules to those. The previous implementation derived the names itself by
    re-walking the grammar -- filters, then ``or``/``and``/``not``, then
    comparisons, then list literals -- and had to be kept in step with
    ``_evaluate_simple_expression`` by hand.

    That is what made this take several rounds: each round fixed one shape the
    walk disagreed about (``inputs.a === inputs.b``, ``bogus == 'x'``, list
    elements, filter arguments, a newline before ``and``) and nothing stopped the
    next one. Reading the leaves off the evaluator removes the class rather than
    another instance of it: the two cannot disagree about where the operands are
    when only one of them decides.
    """
    stripped = text.strip()
    if not stripped:
        return "an operand is empty"

    for leaf in _collect_leaves(stripped):
        reason = _unresolvable_leaf(leaf)
        if reason is not None:
            return reason
    return None


def _wrapping_would_not_repair(core: str) -> str | None:
    """Why wrapping *core* in ``{{ }}`` would not yield the expression intended.

    ``None`` when it would. Each branch names something observable about the text
    itself, deliberately not the interpolator path it will take: two earlier
    versions of this message asserted an internal route -- the raw-close fallback --
    and were wrong, because ``_is_single_expression`` accepts the wrapped form and
    sends it down the typed fast path instead.
    """
    if not core:
        return "there is no expression here to wrap"
    if _has_unbalanced_quote(core):
        return "the quote opened in it is never closed"
    if _has_unbalanced_bracket(core):
        return "its brackets do not balance"
    if _has_incomplete_operand(core):
        return "an operator in it is missing an operand"
    unresolvable = _unresolvable_term(core)
    if unresolvable is not None:
        return unresolvable
    rejected = _evaluator_rejects(core)
    if rejected is not None:
        return f"the evaluator rejects it ({rejected})"
    return None


def format_condition_remediation(condition: Any) -> str:
    """The advice sentence for a condition that is never evaluated.

    ``format_condition_correction`` wraps whatever it is handed, which is right for a
    formatter but wrong to advertise as paste-ready when wrapping cannot repair the
    input. Measured, each of these was being offered as the fix and each **inverts**
    the condition instead:

        "   "                    -> "{{ }}"                      True  -> False
        {{ inputs.name == 'abc   -> "{{ inputs.name == 'abc }}"  True  -> False
        inputs.name ==           -> "{{ inputs.name == }}"       True  -> False

    The author is told the condition is always true, pastes the suggestion, and now
    has an always-false one. Naming the fault beats handing back something that looks
    authoritative and is not -- the same call already made for
    ``condition_has_malformed_expression_block``, which offers no suggestion at all.
    """
    core = _strip_stray_delimiters(str(condition)).strip()
    reason = _wrapping_would_not_repair(core)
    if reason is None:
        return "Wrap the expression: " + format_condition_correction(condition) + "."
    return (
        f"No correction is offered because {reason}: wrapping it as written would "
        "produce a different expression from the one intended, and its result can "
        "silently invert the condition rather than repair it. Complete the "
        "expression, or use the literal true or false."
    )