levain-cli 0.1.0__py3-none-any.whl

levain_recipe/validate.py

@@ -0,0 +1,554 @@
+"""Validation pipeline: parse -> profile -> graph -> translate -> TLC.
+
+Also provides ``validate_package()`` for full recipe package
+validation (PlusCal + Python source + pyproject.toml).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import shutil
+from typing import cast
+
+from ._java import resolve_jar
+from .graph import check_graph
+from .integrations_check import check_mcp_names
+from .models import (
+    CALL_AGENT_BUILTIN,
+    INTERRUPT_BUILTIN,
+    INTERRUPTIBLE_CLASSES,
+    INTERRUPTIBLE_KEY,
+    NodeAnnotation,
+    RoutingTable,
+    StateField,
+    ValidatedSpec,
+    ValidationError,
+)
+from .parser import (
+    extract_constants,
+    extract_defines,
+    extract_variables,
+    parse,
+)
+from .profile import check_profile
+from .reducers import REDUCERS
+from .source_check import check_python_sources
+from .tlc import model_check
+from .translate import translate
+
+log = logging.getLogger(__name__)
+
+_TRUTHY = frozenset({"1", "true", "yes", "on"})
+
+_RE_REDUCER = re.compile(r"\\[*]\s*@reducer\s+(\w+)\s*$")
+# Strip the PlusCal comment prefix ``\*`` (plus surrounding
+# whitespace) from a single-line comment so the recovered body
+# is just the prose the recipe author wrote.
+_RE_COMMENT_PREFIX = re.compile(r"^\\[*]\s?")
+# Any comment line whose body starts with ``@word`` is a
+# structured annotation (``@reducer``, ``@desc``, future tags) —
+# excluded from the free-form description so the help text never
+# accidentally includes machine-readable metadata.
+_RE_ANNOTATION = re.compile(r"^\\[*]\s*@\w+")
+
+
+def validate(
+    source: str,
+    *,
+    attached_mcp_names: list[str] | None = None,
+) -> ValidatedSpec | list[ValidationError]:
+    """Full validation pipeline (stages 1-5 + MCP-name check).
+
+    Runs parse, profile check, graph check, MCP-name resolution,
+    PlusCal translation, and TLC model checking.  Short-circuits
+    on the first stage that fails.
+
+    ``attached_mcp_names`` is forwarded to the MCP-name check —
+    see :func:`validate_fast` for its semantics.
+    """
+    result = validate_fast(source, attached_mcp_names=attached_mcp_names)
+    if isinstance(result, list):
+        return result
+
+    translated = translate(source, result.module_name)
+    if isinstance(translated, list):
+        return translated
+
+    invariants = result.invariants
+    tlc_errors = model_check(translated, result.module_name, invariants)
+    if tlc_errors is not None:
+        return tlc_errors
+
+    return result
+
+
+def validate_fast(  # noqa: PLR0911
+    source: str,
+    *,
+    attached_mcp_names: list[str] | None = None,
+) -> ValidatedSpec | list[ValidationError]:
+    """Fast validation (stages 1-3 + MCP-name check, no Java).
+
+    ``attached_mcp_names``:
+        - ``None`` (default): the MCP-name check reads the target
+          list from ``LEVAIN_TARGET_INTEGRATIONS_B64``.  Empty/
+          missing env var skips the check (clean checkout,
+          manual CLI run with no target context).
+        - explicit list: enforce against the given names plus
+          the platform server names.  Pass ``[]`` to enforce
+          platform-only.
+    """
+    # Stage 1: Parse.
+    parse_result = parse(source)
+    if isinstance(parse_result, list):
+        return parse_result
+
+    algo, module_name = parse_result
+
+    # Stage 2: Profile check.
+    if algo.parent is None or algo.parent.parent is None:
+        return [
+            ValidationError(
+                stage="profile",
+                message=("Unexpected AST structure: missing parent nodes."),
+                line=algo.start_point[0] + 1,
+            )
+        ]
+    profile_result = check_profile(algo, algo.parent.parent)
+    if isinstance(profile_result, list):
+        return profile_result
+
+    annotations, send_fields = profile_result
+
+    # Extract variables and defines.
+    raw_vars = extract_variables(algo)
+    variables, var_errors = _build_state_fields(raw_vars)
+    if var_errors:
+        return var_errors
+
+    constants = extract_constants(algo)
+    invariants = [d for d in extract_defines(algo) if d not in constants]
+
+    # Stage 3: Graph check.  Tell the reachability check that
+    # ``interrupt`` nodes count as termination — a chat-shape
+    # recipe that loops Respond → WaitForMessage (interrupt) →
+    # Respond would otherwise fail "cannot reach Done."
+    interrupt_labels = frozenset(
+        node.label
+        for node in annotations
+        if node.function == INTERRUPT_BUILTIN
+    )
+    graph_result = check_graph(
+        algo, raw_vars, send_fields, terminal_labels=interrupt_labels
+    )
+    if graph_result and isinstance(graph_result[0], ValidationError):
+        return graph_result
+    routing = cast(list[RoutingTable], graph_result)
+
+    # Stage 4: MCP-name resolution.  Verifies every @mcp_servers
+    # entry maps to a known platform server or a target-attached
+    # integration; see ``integrations_check`` for the skip rules.
+    mcp_errors = check_mcp_names(
+        annotations, attached_mcp_names=attached_mcp_names
+    )
+    if mcp_errors:
+        return mcp_errors
+
+    # Stage 5: agent-to-agent call args.  ``call_agent`` nodes need a
+    # target slug and an output mapping, or they're a silent no-op.
+    a2a_errors = _check_call_agent_nodes(annotations)
+    if a2a_errors:
+        return a2a_errors
+
+    # Stage 6: mid-run steering policy.  A typo'd ``interruptible``
+    # value would otherwise silently fall back to the default and the
+    # node would behave unexpectedly under steering.
+    steer_errors = _check_interruptible_nodes(annotations)
+    if steer_errors:
+        return steer_errors
+
+    return ValidatedSpec(
+        source=source,
+        module_name=module_name,
+        variables=variables,
+        nodes=annotations,
+        routing=routing,
+        invariants=invariants,
+        constants=constants,
+    )
+
+
+def _check_call_agent_nodes(
+    annotations: list[NodeAnnotation],
+) -> list[ValidationError]:
+    """Validate ``call_agent`` node args (target + I/O).
+
+    Two shapes are accepted (compiled by the ``call_agent`` dispatch +
+    wait nodes):
+
+    * **Static**: ``agent`` (literal slug), optional ``input`` /
+      required ``output`` — flat ``{str: str}`` field maps. The
+      compiler reads ``input`` as ``{B_field: A_state_field}`` and
+      ``output`` as ``{A_state_field: B_output_field}``.
+    * **Dynamic**: ``agent_state`` (state field holding the target
+      slug), optional ``input_message_state`` (state field holding the
+      overlay dict), required ``output_state`` (state field for the
+      child's output dict).
+
+    A missing target or no output sink makes the node a silent
+    no-op, so both are hard errors.
+    """
+    errors: list[ValidationError] = []
+    for node in annotations:
+        if node.function != CALL_AGENT_BUILTIN:
+            continue
+        label = node.label
+        errors.extend(_check_one_call_agent(node, label))
+    return errors
+
+
+def _check_one_call_agent(
+    node: NodeAnnotation, label: str
+) -> list[ValidationError]:
+    errors: list[ValidationError] = []
+
+    def _nonempty_str(key: str) -> bool:
+        val = node.args.get(key)
+        return isinstance(val, str) and bool(val)
+
+    # Target: a literal ``agent`` slug or a dynamic ``agent_state``
+    # field name.
+    if not _nonempty_str("agent") and not _nonempty_str("agent_state"):
+        errors.append(
+            ValidationError(
+                stage="profile",
+                message=(
+                    f"@node '{label}' uses 'call_agent' but is missing a "
+                    "target: set 'agent' (a slug) or 'agent_state' (a "
+                    "state field name)."
+                ),
+            )
+        )
+
+    # Static input map (optional) must be a string→string map.
+    if node.args.get("input") is not None and not _is_str_map(
+        node.args.get("input")
+    ):
+        errors.append(
+            ValidationError(
+                stage="profile",
+                message=(
+                    f"@node '{label}': 'call_agent' 'input' must be an "
+                    "object mapping field names to field names "
+                    "(string → string)."
+                ),
+            )
+        )
+
+    # Output sink: a non-empty static map or a dynamic state field.
+    out_map = node.args.get("output")
+    has_out_state = _nonempty_str("output_state")
+    if out_map is not None and not _is_str_map(out_map):
+        errors.append(
+            ValidationError(
+                stage="profile",
+                message=(
+                    f"@node '{label}': 'call_agent' 'output' must be an "
+                    "object mapping field names to field names "
+                    "(string → string)."
+                ),
+            )
+        )
+    elif not has_out_state and not (_is_str_map(out_map) and out_map):
+        errors.append(
+            ValidationError(
+                stage="profile",
+                message=(
+                    f"@node '{label}': 'call_agent' has no output sink — "
+                    "map at least one field via 'output' or set "
+                    "'output_state', or the call is a no-op."
+                ),
+            )
+        )
+    return errors
+
+
+def _check_interruptible_nodes(
+    annotations: list[NodeAnnotation],
+) -> list[ValidationError]:
+    """Validate the optional ``interruptible`` value on each node.
+
+    Absent is fine (the compiler defaults it); a present value must be
+    one of the known steering classes so a typo can't silently degrade
+    to the default.  ``interrupt`` (Wait) nodes are paused waiting for
+    user input and can't be cut mid-flight — the compiler never wires
+    steer tracking for them, so setting ``interruptible`` there has no
+    effect and is rejected here.
+    """
+    errors: list[ValidationError] = []
+    for node in annotations:
+        if INTERRUPTIBLE_KEY not in node.args:
+            continue
+        if node.function == INTERRUPT_BUILTIN:
+            errors.append(
+                ValidationError(
+                    stage="profile",
+                    message=(
+                        f"@node '{node.label}': {INTERRUPTIBLE_KEY!r} is not "
+                        "valid on 'interrupt' (Wait) nodes — they pause for "
+                        "user input and are not subject to mid-run steering."
+                    ),
+                )
+            )
+            continue
+        val = node.args[INTERRUPTIBLE_KEY]
+        if val not in INTERRUPTIBLE_CLASSES:
+            errors.append(
+                ValidationError(
+                    stage="profile",
+                    message=(
+                        f"@node '{node.label}': {INTERRUPTIBLE_KEY!r} must "
+                        f"be one of {INTERRUPTIBLE_CLASSES}, got {val!r}."
+                    ),
+                )
+            )
+    return errors
+
+
+def _is_str_map(val: object) -> bool:
+    return isinstance(val, dict) and all(
+        isinstance(k, str) and isinstance(v, str) for k, v in val.items()
+    )
+
+
+def validate_package(
+    recipe_dir: str,
+    *,
+    attached_mcp_names: list[str] | None = None,
+) -> ValidatedSpec | list[ValidationError]:
+    """Validate a full recipe package (PlusCal + Python source).
+
+    Reads ``graph.tla`` from *recipe_dir*, runs the PlusCal
+    validation pipeline, then checks Python source references.
+
+    ``attached_mcp_names`` is forwarded to the MCP-name check —
+    see :func:`validate_fast`.
+    """
+    graph_path = os.path.join(recipe_dir, "graph.tla")
+    if not os.path.isfile(graph_path):
+        return [
+            ValidationError(
+                stage="source",
+                message="graph.tla not found in recipe directory.",
+            )
+        ]
+
+    with open(graph_path, encoding="utf-8") as f:
+        source = f.read()
+
+    # Stages 1-5 when Java + tla2tools.jar are both present, else
+    # 1-3 (fast).  The fast fallback is a local-dev convenience —
+    # in any container meant to run full validation, set
+    # ``LEVAIN_REQUIRE_TLC=1`` so a missing toolchain fails loudly
+    # instead of silently shipping a spec that skipped TLC.
+    if shutil.which("java") and resolve_jar() is not None:
+        result = validate(source, attached_mcp_names=attached_mcp_names)
+    elif _require_tlc():
+        return [
+            ValidationError(
+                stage="tlc",
+                message=(
+                    "TLC model-checking is required (LEVAIN_REQUIRE_TLC set)"
+                    " but the toolchain is missing: "
+                    f"{_missing_tlc_reason()}."
+                ),
+            )
+        ]
+    else:
+        log.info(
+            "validate_package: TLC toolchain unavailable (%s), skipping TLC",
+            _missing_tlc_reason(),
+        )
+        result = validate_fast(source, attached_mcp_names=attached_mcp_names)
+    if isinstance(result, list):
+        return result
+
+    # Stage 6: Python source checks.
+    src_errors = check_python_sources(result, recipe_dir)
+    if src_errors:
+        return src_errors
+
+    return result
+
+
+def _require_tlc() -> bool:
+    """Whether deployed services must run full TLC validation.
+
+    Set in every image that's meant to do full validation
+    (harness worker, platform sandbox, recipe service) so a
+    regression that strips Java/tla2tools surfaces as a hard
+    validation error rather than a silently degraded one.
+    """
+    return os.environ.get("LEVAIN_REQUIRE_TLC", "").strip().lower() in _TRUTHY
+
+
+def _missing_tlc_reason() -> str:
+    """Explain which half of the TLC toolchain is unavailable."""
+    if shutil.which("java") is None:
+        return "java not found on PATH"
+    jar = os.environ.get("TLA2TOOLS_JAR")
+    if jar:
+        return f"tla2tools.jar not found at TLA2TOOLS_JAR={jar!r}"
+    return "tla2tools.jar not found (TLA2TOOLS_JAR not set)"
+
+
+def _build_state_fields(
+    raw_vars: list[dict[str, object]],
+) -> tuple[list[StateField], list[ValidationError]]:
+    """Build StateField objects and surface variable-level errors.
+
+    Checks performed:
+    - ``_``-prefixed names collide with platform metadata keys
+      (``_error``, ``_cost_usd``) written to node results.
+    - Unknown literal types (the parser returned ``"unknown"``
+      because the default value wasn't a recognised literal).
+    - ``@reducer`` annotation points at a blessed reducer in
+      :mod:`levain_recipe.reducers`.
+    - ``list``-typed fields must declare a reducer, since the
+      default "last write wins" behaviour silently drops
+      accumulated items; scalar fields must not (there's no
+      reducer in the registry that would compose correctly).
+    """
+    errors: list[ValidationError] = []
+    fields: list[StateField] = []
+
+    for v in raw_vars:
+        name = str(v["name"])
+        vtype = str(v["type"])
+        raw_line = v.get("line")
+        line = raw_line if isinstance(raw_line, int) else None
+        comments = cast(list[str], v.get("comments") or [])
+
+        if name.startswith("_"):
+            errors.append(
+                ValidationError(
+                    stage="profile",
+                    message=(
+                        f"Variable '{name}' is reserved"
+                        " (names prefixed with '_' are reserved"
+                        " for platform metadata)."
+                    ),
+                    line=line,
+                )
+            )
+            continue
+        if vtype == "unknown":
+            errors.append(
+                ValidationError(
+                    stage="profile",
+                    message=(f"Variable '{name}' has unsupported type."),
+                    line=line,
+                )
+            )
+            continue
+
+        try:
+            reducer = _extract_reducer(comments)
+        except ValueError as exc:
+            errors.append(
+                ValidationError(
+                    stage="profile",
+                    message=f"Variable '{name}': {exc}",
+                    line=line,
+                )
+            )
+            continue
+        if reducer is not None and reducer not in REDUCERS:
+            errors.append(
+                ValidationError(
+                    stage="profile",
+                    message=(
+                        f"Unknown @reducer '{reducer}' on variable"
+                        f" '{name}'. Known:"
+                        f" {', '.join(sorted(REDUCERS))}."
+                    ),
+                    line=line,
+                )
+            )
+            continue
+        if vtype == "list" and reducer is None:
+            errors.append(
+                ValidationError(
+                    stage="profile",
+                    message=(
+                        f"List variable '{name}' must declare a"
+                        " @reducer — the default last-write-wins"
+                        " behaviour drops accumulated items."
+                    ),
+                    line=line,
+                )
+            )
+            continue
+        if vtype != "list" and reducer is not None:
+            errors.append(
+                ValidationError(
+                    stage="profile",
+                    message=(
+                        f"@reducer is only valid on list variables"
+                        f" (got '{vtype}' on '{name}')."
+                    ),
+                    line=line,
+                )
+            )
+            continue
+
+        fields.append(
+            StateField(
+                name=name,
+                type=vtype,
+                default=v["default"],
+                reducer=reducer,
+                description=_extract_description(comments),
+            )
+        )
+
+    return fields, errors
+
+
+def _extract_description(comments: list[str]) -> str | None:
+    r"""Return the free-form description from the comment list.
+
+    Joins every comment line that is *not* an ``@``-prefixed
+    annotation, stripping the leading ``\*`` prefix and
+    collapsing the result into one paragraph. Returns ``None``
+    when the variable has no descriptive comments.
+    """
+    parts: list[str] = []
+    for text in comments:
+        if _RE_ANNOTATION.match(text):
+            continue
+        body = _RE_COMMENT_PREFIX.sub("", text).strip()
+        if body:
+            parts.append(body)
+    if not parts:
+        return None
+    return " ".join(parts)
+
+
+def _extract_reducer(comments: list[str]) -> str | None:
+    """Return the ``@reducer <name>`` from the comment list, or None.
+
+    Raises ``ValueError`` if more than one ``@reducer`` annotation
+    is present — the caller wraps it in a ``ValidationError`` so
+    duplicates surface instead of being silently dropped.
+    """
+    matches = [
+        m.group(1) for text in comments if (m := _RE_REDUCER.match(text))
+    ]
+    if len(matches) > 1:
+        raise ValueError(
+            f"multiple @reducer annotations {matches}; declare at most one."
+        )
+    return matches[0] if matches else None