clankloop 0.0.0__py3-none-any.whl

clankloop/core/env.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+"""Environment and templating — key-path navigation, values, and ClankTemplate rendering.
+
+The environment is a tree of :class:`Object` nodes holding :class:`Value` leaves
+and :class:`Locator` aliases. Values are accessed via dotted key paths (e.g.
+``pipeline.globals.workdir``).
+
+:class:`ClankTemplate` allows recursive rendering of templates with values from
+the environment.
+"""
+
+
+import logging
+from dataclasses import dataclass
+from typing import Callable, Iterable, Iterator, Protocol, runtime_checkable
+from string import Template
+
+from clankloop.core.errors import (
+    ImmutableValueError,
+    UnassignedValueError,
+    UnknownKeyError,
+)
+
+logger = logging.getLogger("clankloop")
+
+__all__ = [
+    "Object",
+    "Value",
+    "EnvPath",
+    "ClankTemplate",
+    "data_dependencies",
+]
+
+
+RESULT_T = str | int
+
+
+@dataclass(frozen=True)
+class EnvPath:
+    """A first-class environment path, stored as segments.
+
+    The dotted-string form (e.g. ``pipeline.globals.workdir``) is the
+    serialization, produced by :meth:`__str__` and consumed by :meth:`parse`.
+    The env module stores and navigates paths structurally via segments held
+    privately; callers interact through semantic accessors (:meth:`head`,
+    :meth:`tail`, :attr:`leaf`) rather than indexing.
+
+    ``Object.evaluate`` / ``set_value`` / ``locate`` take ``EnvPath``;
+    callers parse dotted strings at the boundary via :meth:`parse`, or
+    construct from segments via :meth:`of`.
+    """
+
+    _segments: tuple[str, ...]
+
+    @classmethod
+    def parse(cls, dotted: str) -> "EnvPath":
+        return cls(tuple(dotted.split("."))) if dotted else cls(())
+
+    @classmethod
+    def of(cls, *segments: str) -> "EnvPath":
+        """Construct a path from its segments."""
+        return cls(segments)
+
+    def __str__(self) -> str:
+        return ".".join(self._segments)
+
+    @property
+    def leaf(self) -> str:
+        return self._segments[-1]
+
+    @property
+    def head(self) -> str:
+        return self._segments[0]
+
+    def tail(self) -> "EnvPath | None":
+        """Return the path minus its first segment, or ``None`` if there is no
+        segment beyond the head."""
+        if len(self._segments) < 2:
+            return None
+        return EnvPath(self._segments[1:])
+
+
+class ClankTemplate(Template):
+    idpattern = r"(?a:[_a-z][_a-z0-9\.]*)"
+
+    def render(self, root: "Object") -> str:
+        """Substitute every identifier by evaluating it against *root*."""
+        variables: dict[str, str] = {}
+        for parameter in self.get_identifiers():
+            variables[parameter] = str(root.evaluate(EnvPath.parse(parameter)))
+        return self.substitute(variables)
+
+
+#: What a :class:`Value` stores: an evaluated literal or an (immutable)
+#: template re-rendered on read. Extends :data:`RESULT_T` with the template
+#: case; runtime writes (``set_value``) take only literals.
+VALUE_T = RESULT_T | ClankTemplate
+
+
+@runtime_checkable
+class Locator(Protocol):
+    """Protocol for objects that can locate values by key path."""
+
+    def locate(self, key_path: EnvPath, root: "Object") -> "Object": ...
+
+
+@dataclass
+class Value:
+    """A leaf in the environment holding a literal or a render template.
+
+    The stored ``value`` is either a literal (``str`` or ``int``) returned
+    verbatim, or a :class:`ClankTemplate` re-rendered against the env on each
+    read. Which it is is determined by type, not a flag.
+
+    A mutable value (``immutable=False``) cannot hold a template: rendering
+    re-interprets the stored string as a template at read time, so a mutable
+    template value would let a runtime write (e.g. a task's stdout captured
+    into a global) inject template identifiers whose transitive read set is
+    not statically knowable. Restricting templates to immutable values keeps
+    the transitive read set a compile-time property.
+    """
+
+    value: VALUE_T
+    immutable: bool = True
+    assigned: bool = False
+
+    def __post_init__(self) -> None:
+        if isinstance(self.value, ClankTemplate) and not self.immutable:
+            raise ImmutableValueError(
+                "A mutable Value cannot hold a render template "
+                "(immutable=False with a ClankTemplate value is not allowed)"
+            )
+
+    def evaluate(self, context: "Object") -> RESULT_T:
+        if not self.assigned:
+            raise UnassignedValueError("Accessed unassigned literal value")
+
+        if isinstance(self.value, ClankTemplate):
+            return self.value.render(context)
+
+        return self.value
+
+    def set_value(self, new_value: RESULT_T) -> None:
+        if self.immutable and self.assigned:
+            raise ImmutableValueError("Cannot modify assigned immutable literal value")
+
+        self.assigned = True
+        self.value = new_value
+
+    def template_identifiers(self) -> frozenset[str]:
+        """Identifiers embedded in this value's template, or empty if literal."""
+        if isinstance(self.value, ClankTemplate):
+            return frozenset(self.value.get_identifiers())
+        return frozenset()
+
+
+@dataclass
+class Alias(Locator):
+    """Represents an alias to another object in the environment."""
+
+    alias_fn: Callable[["Object"], Locator]
+
+    def locate(self, key_path: EnvPath, root: "Object") -> "Object":
+        return self.alias_fn(root).locate(key_path, root)
+
+
+class Object(Locator):
+    """Represents a node in the environment tree, holding values and locators."""
+
+    def __init__(self, entries: dict[str, Value | Locator]) -> None:
+        self.entries = entries
+
+
+    def evaluate(self, key_path: EnvPath) -> RESULT_T:
+        """Evaluate the value at the given key path, resolving any aliases and
+        rendering templates as needed."""
+
+        value = self.locate(key_path, self)
+        logger.debug(
+            "Evaluating key_path",
+            extra={"key_path": str(key_path), "value": value},
+        )
+        leaf = value.entries[key_path.leaf]
+        assert isinstance(leaf, Value), f"Leaf at {key_path!s} is not a Value"
+        return leaf.evaluate(self)
+
+    def locate(self, key_path: EnvPath, root: "Object") -> "Object":
+        """Locate the object corresponding to the given key path, resolving any aliases."""
+        item_key = key_path.head
+        tail = key_path.tail()
+
+        logger.debug("Locating key", extra={"item_key": item_key, "tail": tail})
+        if item_key not in self.entries:
+            logger.debug("Key %s not in %s", item_key, root)
+            raise UnknownKeyError(f"Object has no attribute {item_key!r}")
+
+        if tail is None:
+            logger.debug(
+                "Returning value for key",
+                extra={"item_key": item_key, "value": self.entries[item_key]},
+            )
+            return self
+
+        logger.debug(
+            "Navigating to nested key",
+            extra={"tail": tail, "item_key": item_key},
+        )
+        next_locator = self.entries[item_key]
+        assert isinstance(
+            next_locator, Locator
+        ), f"Intermediate at {item_key!r} is not a Locator"
+        return next_locator.locate(tail, root)
+
+    def set_value(self, key_path: EnvPath, value: RESULT_T) -> None:
+        """Set the value at the given key path, resolving any aliases and
+        ensuring immutability rules are respected."""
+
+        logger.debug(
+            "Setting value for key_path",
+            extra={"key_path": str(key_path), "value": value},
+        )
+        value_obj = self.locate(key_path, self)
+        leaf = value_obj.entries[key_path.leaf]
+        assert isinstance(leaf, Value), f"Leaf at {key_path!s} is not a Value"
+        leaf.set_value(value)
+
+    def __repr__(self) -> str:
+        def build_paths(
+            current: Object, prefix: str = ""
+        ) -> list[tuple[str, Value | Locator | str]]:
+            paths = []
+            if len(current.entries) == 0:
+                return [(prefix, "Empty")]
+
+            for key, val in current.entries.items():
+                path = f"{prefix}.{key}" if prefix else key
+                if isinstance(val, Object):
+                    paths.extend(build_paths(val, path))
+                else:
+                    paths.append((path, val))
+            return paths
+
+        paths = build_paths(self)
+        paths.sort(key=lambda x: x[0])
+        return "\n".join(f"{p[0]}: {p[1]}" for p in paths)
+
+
+def locator_values(root: Locator, prefix: str = "") -> Iterator[tuple[str, Value]]:
+    """Yield ``(dotted_path, Value)`` for each Value leaf declared under *root*.
+
+    A container walk over the env's declared values, emitting root-relative
+    dotted paths. Aliases are pointers, not containers -- they declare no
+    values of their own -- so the walk never recurses through one (which would
+    otherwise duplicate the target's leaves under the alias's path, or loop).
+    """
+    if not isinstance(root, Object):
+        return
+    for key, val in root.entries.items():
+        path = f"{prefix}.{key}" if prefix else key
+        if isinstance(val, Object):
+            yield from locator_values(val, path)
+        elif isinstance(val, Value):
+            yield (path, val)
+
+
+def data_dependencies(root: Locator, roots: Iterable[str]) -> frozenset[str]:
+    """Close a set of env paths through render templates.
+
+    Each path plus the identifiers embedded in any render value reached,
+    recursively. Recursion bottoms out because only immutable values can
+    hold a template, so a reached value's template contents are statically
+    known. Paths that resolve to no declared value are included as leaves
+    (they are read, even if reading would fail); assignment is not checked
+    here.
+    """
+    leaves = dict(locator_values(root))
+    seen: set[str] = set()
+    stack: list[str] = list(roots)
+    while stack:
+        path_str = stack.pop()
+        if path_str in seen:
+            continue
+        seen.add(path_str)
+        leaf = leaves.get(path_str)
+        if leaf is not None:
+            stack.extend(leaf.template_identifiers())
+    return frozenset(seen)
+
+
+def assigned_paths(root: Locator) -> frozenset[str]:
+    """Dotted paths to every assigned Value leaf declared under *root*."""
+    return frozenset(path for path, v in locator_values(root) if v.assigned)

clankloop/core/errors.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Exception hierarchy for clankloop.
+
+One root — :class:`ClankloopError` — so callers can catch any clankloop-raised
+exception with a single ``except``. The three subtrees mirror the package's
+concerns: :class:`EnvError` (environment/templating), :class:`GraphError`
+(control-flow analysis and runtime), and :class:`ParameterError` (caller-side
+parameter binding).
+
+All exceptions live here so the error surface is greppable in one place.
+"""
+
+
+
+class ClankloopError(Exception):
+    """Root of every exception clankloop raises."""
+
+
+class EnvError(ClankloopError):
+    """Base for environment/templating errors."""
+
+
+class UnassignedValueError(EnvError):
+    """Raised when trying to evaluate an unassigned value."""
+
+
+class ImmutableValueError(EnvError):
+    """Raised when trying to modify an already-assigned immutable value."""
+
+
+class UnknownKeyError(EnvError):
+    """Raised when a key path references a key that does not exist."""
+
+
+class GraphError(ClankloopError):
+    """Base for execution-graph errors (static analysis and runtime)."""
+
+
+class UnexpectedTerminationError(GraphError):
+    """Raised when a task exits with a non-zero code and no failure branch matched."""
+
+
+class UnknownTaskError(GraphError):
+    """A branch targets a task that is not in the graph.
+
+    Raised at compile time by the graph validator (a configuration error) and at
+    runtime by execute() as a safety net against dangling branch targets.
+    """
+
+
+class InfiniteLoopError(GraphError):
+    """A reachable execution path never terminates.
+
+    Raised when the state-space walk revisits a (task, retry-budget-vector)
+    state already on its DFS stack. Because retry budgets only decrement,
+    such a revisit means the path repeats forever without exhausting a budget.
+    """
+
+
+class UnassignedDataDependencyError(GraphError):
+    """A task reads an env path that no reachable producer assigns.
+
+    Raised when the state-space walk reaches a task whose read set includes a
+    path not in the assigned set on the current path. Assignment grows
+    monotonically along a path as producers (SetActions on matched branches)
+    fire; the check is therefore path-sensitive.
+    """
+
+
+class ParameterError(ClankloopError):
+    """Base for parameter-binding errors."""
+
+
+class MissingParameterError(ParameterError):
+    """Raised when a required parameter is not supplied for a pipeline run."""
+
+
+class UnknownParameterError(ParameterError):
+    """Raised when a supplied parameter name is not declared in the pipeline."""

clankloop/core/graph.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+"""Execution graph engine — tasks, conditions, actions, and graph execution.
+
+The execution graph (:class:`ExecutionGraph`) is the core runtime structure. It
+holds a set of :class:`~clankloop.core.types.Execution` tasks, their branching
+logic (conditions and actions), and a shared environment
+(:class:`~clankloop.core.env.Object`).
+
+This module is the public surface of the ``clankloop.core`` package: it
+re-exports the domain types (:mod:`clankloop.core.types`), the error classes
+(:mod:`clankloop.core.errors`), the bash execution backend
+(:mod:`clankloop.core.bash`), and the LTS analyser
+(:mod:`clankloop.core.lts`) so callers can import everything from
+``clankloop.core.graph``.
+"""
+
+
+import logging
+from typing import Mapping, Sequence
+
+from clankloop.core.env import ClankTemplate  # noqa: F401
+from clankloop.core.env import Object
+from clankloop.core.errors import (  # noqa: F401
+    InfiniteLoopError,
+    UnexpectedTerminationError,
+    UnassignedDataDependencyError,
+    UnknownTaskError,
+)
+# BashExecution is the one Execution backend shipped in core.
+from clankloop.core.bash import BashExecution  # noqa: F401
+# LTS analyser — the public entry points the facade re-exports.
+from clankloop.core.lts import (
+    LabeledTransitionSystem,
+    analyze,
+    data_dependencies as _data_dependencies,
+    validate_data_dependencies as _validate_data_dependencies,
+)
+# Domain types — the public surface re-exported from the types module.
+from clankloop.core.types import (
+    Action,
+    AlwaysCondition,
+    Condition,
+    Execution,
+    ExecutionContext,
+    ExecutionResult,
+    IOChannels,
+    NextAction,
+    OnFailureCondition,
+    OnRetryCondition,
+    OnSuccessCondition,
+    SetAction,
+)
+
+logger = logging.getLogger("clankloop")
+
+__all__ = [
+    "ExecutionGraph",
+    "BashExecution",
+    "Execution",
+    "Condition",
+    "Action",
+    "OnSuccessCondition",
+    "OnFailureCondition",
+    "AlwaysCondition",
+    "OnRetryCondition",
+    "SetAction",
+    "NextAction",
+    "ExecutionResult",
+    "ExecutionContext",
+    "IOChannels",
+    "UnexpectedTerminationError",
+    "UnknownTaskError",
+    "InfiniteLoopError",
+    "UnassignedDataDependencyError",
+    "analyze",
+    "LabeledTransitionSystem",
+    "ClankTemplate",
+]
+
+
+class ExecutionGraph:
+    """A directed execution graph of tasks with conditional branching.
+
+    The graph holds named executions, their action branches (condition → actions),
+    and a shared environment. Execution starts at the entry task and walks
+    forward, evaluating conditions to pick the next task, set variables, or abort.
+
+    Attributes:
+        name: The pipeline name.
+        execs: Mapping of task name to :class:`Execution`.
+        exec_actions: Mapping of task name to branches (condition, actions).
+        env: The shared environment object.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        execs: dict[str, "Execution"],
+        exec_actions: dict[str, Sequence[tuple[Condition, Sequence[Action]]]],
+        env: Object,
+    ):
+        self.name = name
+        self.execs = execs
+        self.exec_actions = exec_actions
+        self.env = env
+
+    def captures_stdio(self, task: str) -> bool:
+        """Whether any branch of *task* captures stdout/stderr into a SetAction.
+
+        Such tasks must run captured even under ``--interactive``: making them
+        interactive would starve the capture their SetActions depend on.
+        """
+        return any(
+            isinstance(action, SetAction) and (action.stdout or action.stderr)
+            for _cond, actions in self.exec_actions.get(task, [])
+            for action in actions
+        )
+
+    def validate(
+        self,
+        entry_task: str,
+        *,
+        parameter_paths: frozenset[str] = frozenset(),
+        check_data_dependencies: bool = False,
+    ) -> None:
+        """Statically verify the graph is well-formed before execution.
+
+        Builds the labeled transition system (raising ``UnknownTaskError`` for
+        a dangling branch target, ``InfiniteLoopError`` for an unbounded cycle
+        detected during construction) and, when ``check_data_dependencies`` is
+        set, runs the path-sensitive data-dependency check
+        (``UnassignedDataDependencyError``). Graph-only: no subprocess, no
+        env rendering.
+
+        The data-dependency check requires a loopfile format whose env layout
+        makes read sets statically determinable; formats that cannot support
+        it (e.g. v1) leave it off and rely on the runtime
+        ``UnassignedValueError`` safety net.
+
+        Args:
+            entry_task: The task the walk starts from.
+            parameter_paths: Env paths of declared parameters, which count as
+                assigned from the walk's start.
+            check_data_dependencies: Run the data-dependency phase.
+        """
+        lts = analyze(self, entry_task, parameter_paths=parameter_paths)
+        if check_data_dependencies:
+            _validate_data_dependencies(lts, _data_dependencies(self))
+
+    def execute(
+        self,
+        exec_name: str,
+        *,
+        environ: Mapping[str, str],
+        io: IOChannels | None = None,
+        interactive: bool = False,
+    ) -> None:
+        """Walk the graph from *exec_name* against a pre-bound environment.
+
+        Parameters must be bound before this is called — via
+        :meth:`~clankloop.runner.Pipeline.bind`, which translates,
+        validates, and writes caller-supplied values into the env. The graph
+        executes a bound env; it never sees bare parameter names.
+
+        Args:
+            exec_name: The name of the entry task.
+            environ: Base process environment for subprocess execution;
+                pipeline-declared values override it. Supplied by the caller
+                (the CLI reads ``os.environ`` once at the boundary).
+            io: CLI-owned streams the core tees subprocess output through.
+                Defaults to discard-forward + capture (today's behaviour).
+            interactive: When set, tasks whose branches capture no stdio
+                inherit the tty (stdin/stdout/stderr from *io*) so interactive
+                commands work; tasks that capture stdio always run captured.
+
+        Raises:
+            UnexpectedTerminationError: If a task fails and no failure branch
+                matches.
+        """
+        if io is None:
+            io = IOChannels()
+        current_execution: Execution | None = self.execs[exec_name]
+
+        while current_execution is not None:
+            current_task_name = current_execution.name
+            logger.info(
+                "Executing task",
+                extra={"pipeline": self.name, "task": current_task_name},
+            )
+
+            task_io = self._select_task_io(current_task_name, io, interactive)
+            context = ExecutionContext(env=self.env, environ=environ, io=task_io)
+            out = current_execution.execute(context)
+
+            logger.debug(
+                "Execution result",
+                extra={
+                    "pipeline": self.name,
+                    "task": current_task_name,
+                    "stdout": out.stdout,
+                    "stderr": out.stderr,
+                    "returncode": out.returncode,
+                },
+            )
+
+            matched, next_exec_name = self._resolve_branch(current_task_name, out)
+
+            if out.returncode != 0 and not matched:
+                raise UnexpectedTerminationError(
+                    f"Task {current_task_name!r} in pipeline {self.name!r} "
+                    f"terminated unexpectedly with exit code {out.returncode}."
+                    f"Stdout: {out.stdout}\nStderr: {out.stderr}"
+                )
+
+            if next_exec_name is None:
+                current_execution = None
+                continue
+
+            logger.debug(
+                "Next task determined",
+                extra={"pipeline": self.name, "next_task": next_exec_name},
+            )
+            if next_exec_name not in self.execs:
+                raise UnknownTaskError(
+                    f"Task {current_task_name!r} in pipeline {self.name!r} "
+                    f"branches to unknown task {next_exec_name!r}"
+                )
+            current_execution = self.execs[next_exec_name]
+            logger.debug(
+                "Execution loop iteration complete",
+                extra={"pipeline": self.name},
+            )
+
+    def _select_task_io(
+        self, task: str, io: IOChannels, interactive: bool
+    ) -> IOChannels:
+        """Pick the IO channels for *task* under the current interactivity mode.
+
+        A task inherits the tty only under ``--interactive`` AND when it
+        captures no stdio into a SetAction (capturing tasks must run
+        captured). stdin presence is the signal :class:`BashExecution` reads.
+        """
+        if interactive and not self.captures_stdio(task):
+            return io
+        return IOChannels(stdin=None, stdout=io.stdout, stderr=io.stderr)
+
+    def _resolve_branch(
+        self, task: str, result: ExecutionResult
+    ) -> tuple[bool, str | None]:
+        """Resolve the branch outcome for *task* given *result*.
+
+        Mirrors the LTS walker's ``_resolve_outcome``: the first matching
+        condition wins; its actions run in order, and the first NextAction
+        redirects. Returns ``(matched, next_task)`` — ``matched`` is True if
+        any condition matched, ``next_task`` is the redirect target or None.
+        """
+        for condition, actions in self.exec_actions.get(task, []):
+            if not condition.matches(result):
+                continue
+            logger.debug(
+                "Condition matched",
+                extra={
+                    "pipeline": self.name,
+                    "condition": condition.__class__.__name__,
+                },
+            )
+            for action in actions:
+                next_name = action.next(self.env, result)
+                if next_name is not None:
+                    return (True, next_name)
+            return (True, None)
+        return (False, None)