clankloop 0.0.0__py3-none-any.whl

clankloop/loopfile/v2/module.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Module system for v2 loopfiles — protocols, dependencies, and ordering.
+
+A :class:`Module` receives a :class:`~clankloop.loopfile.v2.loopfile.Loopfile`
+spec and returns a transformed one, typically injecting setup/teardown tasks.
+Modules are registered by name in a :class:`~clankloop.loopfile.v2.module_registry.ModuleRegistry`
+and applied in dependency-resolved order (via the ``after`` field on
+:class:`~clankloop.loopfile.v2.loopfile.ModuleSpec` and module-declared ordering
+constraints).
+
+Three sources of ordering constraints are merged into one graph:
+
+1. **Dependencies** (``DEPENDENCIES``) — presence only, no ordering edge. A
+   module needs its dependencies registered at a compatible version, but
+   dependency does not imply application order.
+2. **Module-declared ordering** (``APPLY_BEFORE`` / ``APPLY_AFTER``) — wrapping
+   semantics. ``GitModule`` applies before ``workdir`` because git's tasks
+   go inside workdir's wrapper tasks.
+3. **User-declared ordering** (``after`` on ``ModuleSpec``) — supplemental
+   edges for cases the module author didn't anticipate.
+
+Sources 2 and 3 are equal-weight edges in the same directed graph. If they
+conflict (cycle), the error attributes the cycle to its source constraints.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from clankloop.loopfile.v2.loopfile import Loopfile
+
+
+@dataclass(frozen=True)
+class ModuleDependency:
+    """A module's declaration that another module must be present.
+
+    A dependency is a *presence* constraint, not an *ordering* constraint.
+    The depending module needs its dependency registered at a compatible
+    version, but the application order is determined separately by
+    ordering constraints.
+
+    Attributes:
+        name: The required module's name.
+        version: A semantic version range (e.g. ``\">=1.0"``).
+    """
+
+    name: str
+    version: str
+
+
+class Module(Protocol):
+    """A transform applied to a loopfile spec before compilation.
+
+    Concrete modules declare three class-level facts:
+
+    - ``VERSION`` — the module's semantic version string.
+    - ``DEPENDENCIES`` — a tuple of :class:`ModuleDependency` (presence
+      constraints, no ordering implied).
+    - ``APPLY_BEFORE`` / ``APPLY_AFTER`` — tuples of module names that this
+      module must be applied before / after (wrapping semantics).
+    """
+
+    VERSION: str
+    DEPENDENCIES: tuple[ModuleDependency, ...]
+    APPLY_BEFORE: tuple[str, ...]
+    APPLY_AFTER: tuple[str, ...]
+
+    def transform_loopfile(self, src: Loopfile) -> Loopfile: ...

clankloop/loopfile/v2/module_registry.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Module registry — maps module names to their implementing classes.
+
+A :class:`ModuleRegistry` holds the set of available v2 loopfile transform modules
+and is consulted by the compiler to resolve ``modules:`` entries.
+
+When a module is registered, its dependencies (declared via
+``DEPENDENCIES`` on the module class) must already be in the registry at
+compatible versions. This ensures the registry is always a closed, valid
+dependency set.
+"""
+from typing import Self
+
+from clankloop.loopfile.v2.module import Module
+from clankloop.loopfile.v2.clankshed_module import ClankshedModule
+from clankloop.loopfile.v2.git_module import GitModule
+from clankloop.loopfile.v2.workdir_module import WorkdirModule
+
+
+class ModuleRegistry:
+    """Registry of available modules by name.
+
+    Modules are registered by name and retrieved during compilation to
+    transform loopfile specs. Registration validates that the module's
+    declared dependencies are already registered at compatible versions.
+    """
+
+    def __init__(self) -> None:
+        self._modules: dict[str, type[Module]] = {}
+
+    def register(self, name: str, module_cls: type[Module]) -> None:
+        for dep in module_cls.DEPENDENCIES:
+            if dep.name not in self._modules:
+                raise MissingModuleDependencyError(
+                    f"Cannot register module {name!r}: it requires "
+                    f"{dep.name!r} which is not registered"
+                )
+        self._modules[name] = module_cls
+
+    def get(self, name: str) -> type[Module]:
+        return self._modules[name]
+
+    @classmethod
+    def with_builtins(cls) -> Self:
+        registry = cls()
+        registry.register("workdir", WorkdirModule)
+        registry.register("git", GitModule)
+        registry.register("clankshed", ClankshedModule)
+        return registry
+
+
+class MissingModuleDependencyError(ValueError):
+    """Raised when registering a module whose dependencies are not present."""

clankloop/loopfile/v2/paths.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Env-path builders for the v2 loopfile layout.
+
+v2 uses a *namespaced* environment under a =pipeline= root:
+- =pipeline.name= — the pipeline identifier.
+- =pipeline.constants.<k>= — declared constants.
+- =pipeline.parameters.<n>= — declared parameters.
+- =pipeline.globals.<n>= — pipeline locals / mutable scratch space.
+
+The builders here are the single source of truth for that layout — callers
+supply the leaf name, the builder supplies the prefix (the namespace is
+implied by *which* builder was called). This is the place to review the v2
+path schema. Future layout features (a =pipeline.current_action= alias,
+array/stack segments) extend this module.
+"""
+
+
+from clankloop.core.env import EnvPath
+
+
+def pipeline_name() -> EnvPath:
+    """The pipeline identifier path: =pipeline.name=."""
+    return EnvPath.of("pipeline", "name")
+
+
+def constant(name: str) -> EnvPath:
+    """A declared constant's path: =pipeline.constants.<name>=."""
+    return EnvPath.of("pipeline", "constants", name)
+
+
+def parameter(name: str) -> EnvPath:
+    """A declared parameter's path: =pipeline.parameters.<name>=."""
+    return EnvPath.of("pipeline", "parameters", name)
+
+
+def glob(name: str) -> EnvPath:
+    """A pipeline global (local) path: =pipeline.globals.<name>=."""
+    return EnvPath.of("pipeline", "globals", name)

clankloop/loopfile/v2/toposort.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Topological sort with edge-source attribution.
+
+A generic graph utility — knows nothing about modules. Returns nodes in
+application order given a node list and labelled edges. Cycle errors carry
+the source labels of the edges that form the cycle.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class OrderedEdge:
+    """A directed edge ``(before, after)`` with a source label.
+
+    ``before`` must appear before ``after`` in the result. ``source`` is a
+    human-readable description of where the constraint came from, used in
+    cycle error messages for attribution.
+    """
+
+    before: str
+    after: str
+    source: str
+
+
+class CycleError(ValueError):
+    """Raised when the ordering constraints form a cycle.
+
+    The message attributes the cycle to the edges (by their source labels)
+    that form it.
+    """
+
+    def __init__(self, nodes: set[str], edges: list[OrderedEdge]) -> None:
+        sources = ", ".join(e.source for e in edges)
+        super().__init__(
+            f"Circular ordering detected among {sorted(nodes)}; "
+            f"conflicting constraints: {sources}"
+        )
+
+
+def topological_sort(nodes: list[str], edges: list[OrderedEdge]) -> list[str]:
+    """Return *nodes* in topological order (Kahn's algorithm).
+
+    Only edges where both endpoints are in *nodes* are considered; edges
+    referencing absent nodes are silently ignored.
+
+    Raises:
+        CycleError: If the constraints form a cycle, with attribution to
+            the edges among the cycle's nodes.
+    """
+    node_set = set(nodes)
+    relevant = [e for e in edges if e.before in node_set and e.after in node_set]
+
+    in_degree: dict[str, int] = {n: 0 for n in nodes}
+    adj: dict[str, list[str]] = {n: [] for n in nodes}
+    for edge in relevant:
+        adj[edge.before].append(edge.after)
+        in_degree[edge.after] += 1
+
+    queue = [n for n in nodes if in_degree[n] == 0]
+    result: list[str] = []
+    while queue:
+        n = queue.pop(0)
+        result.append(n)
+        for m in adj[n]:
+            in_degree[m] -= 1
+            if in_degree[m] == 0:
+                queue.append(m)
+
+    if len(result) != len(nodes):
+        remaining = set(nodes) - set(result)
+        cycle_edges = [e for e in relevant if e.before in remaining and e.after in remaining]
+        raise CycleError(remaining, cycle_edges)
+
+    return result

clankloop/loopfile/v2/workdir_module.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""Workdir module — injects a temporary working directory into the pipeline.
+
+Adds a ``workdir-setup`` task (creates a temp dir, exports its path to
+``pipeline.globals.workdir``) at the start and a ``workdir-remove`` task
+(cleans up the directory) at the end.
+"""
+from clankloop.loopfile.v2.module import Module, ModuleDependency
+
+from clankloop.loopfile.v2.loopfile import Loopfile, BashTask, SetAction
+
+
+class WorkdirModule(Module):
+    VERSION = "1.0.0"
+    DEPENDENCIES: tuple[ModuleDependency, ...] = ()
+    APPLY_BEFORE: tuple[str, ...] = ()
+    APPLY_AFTER: tuple[str, ...] = ()
+
+    def __init__(self, **module_args):
+        pass
+
+    def transform_loopfile(self, src: Loopfile) -> Loopfile:
+        new_locals = src.locals + ["workdir"]
+        new_tasks = [
+            BashTask(
+                name="workdir-setup",
+                cmds="mktemp -d | tr -d '\n'",
+                on_success=[SetAction(set="workdir", value="stdout")],
+            ),
+            *src.tasks,
+            BashTask(name="workdir-remove", cmds="rm -rf ${pipeline.globals.workdir}"),
+        ]
+        return Loopfile(
+            name=src.name,
+            constants=src.constants,
+            locals=new_locals,
+            tasks=new_tasks,
+            parameters=src.parameters,
+            modules=src.modules,
+        )

clankloop/loopfile/versions.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""Loopfile version constants."""
+
+
+
+CURRENT_VERSION = "1"
+SUPPORTED_VERSIONS: tuple[str, ...] = ("1", "2")
+
+
+def normalize_version(version: object) -> str:
+    """Coerce a YAML-parsed loopfile version to a canonical string.
+
+    YAML parses ``version: 1`` as int and ``version: 2.0`` as float; both map
+    to the same conceptual version. Integral floats are collapsed so ``2.0``
+    and ``2`` compare equal.
+    """
+    if isinstance(version, float) and version.is_integer():
+        return str(int(version))
+    return str(version)

clankloop/plantuml.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""PlantUML diagram generation — renders a labeled transition system as an activity diagram.
+
+The renderer is a pure projection over the LTS: it knows nothing about
+conditions, actions, or retry types. Nodes are projected by task (collapsing
+the retry-budget dimension), and terminal outcomes (a task with no outgoing
+edge for a given outcome) are emitted as edges to ``[*]``.
+"""
+
+
+from collections import deque
+
+from clankloop.core.lts import LTSNode, LabeledTransitionSystem
+
+
+def _task_id(task_name: str) -> str:
+    return task_name.replace(" ", "_").replace("-", "_")
+
+
+def generate_plantuml(lts: LabeledTransitionSystem) -> str:
+    """Generate a PlantUML state diagram for a labeled transition system.
+
+    Projects LTS nodes by task (collapsing the retry-counter dimension) and
+    emits one ``state`` node per task, ``[*] --> entry``, labelled edges, and
+    ``--> [*]`` for terminal outcomes (a task with no outgoing edge for that
+    outcome).
+
+    Args:
+        lts: The labeled transition system to visualise.
+
+    Returns:
+        A complete PlantUML document string (``@startuml`` … ``@enduml``).
+    """
+    # Tasks in LTS-discovery order (start first), for stable output.
+    seen = list(dict.fromkeys(node.task for node in _discovery_order(lts)))
+
+    # Edges collapsed to (source_task, target_task, label), deduped.
+    collapsed = {(e.source.task, e.target.task, e.label) for e in lts.edges}
+
+    state_lines = [f'state "{task}" as {_task_id(task)}' for task in seen]
+
+    # Group edges by source task in LTS-discovery order.
+    by_source: dict[str, list[tuple[str, str]]] = {}
+    for src, tgt, label in collapsed:
+        by_source.setdefault(src, []).append((tgt, label))
+
+    edge_lines: list[str] = []
+    for task in seen:
+        tid = _task_id(task)
+        outgoing = by_source.get(task, [])
+        labels_out = {label for _tgt, label in outgoing}
+
+        edge_lines.extend(
+            f"{tid} --> {_task_id(target)} : {label}"
+            for target, label in outgoing
+        )
+        # Terminal outcomes: outcomes no edge covers → [*].
+        if "On Success" not in labels_out and "Always" not in labels_out:
+            edge_lines.append(f"{tid} --> [*] : On Success")
+        if "On Failure" not in labels_out and "Always" not in labels_out:
+            edge_lines.append(f"{tid} --> [*] : On Failure")
+
+    lines = [
+        "@startuml",
+        *state_lines,
+        "",
+        f"[*] --> {_task_id(lts.start.task)}",
+        *edge_lines,
+        "@enduml",
+    ]
+    return "\n".join(lines)
+
+
+def _discovery_order(lts: LabeledTransitionSystem) -> list[LTSNode]:
+    """Return LTS nodes in BFS order from the start node."""
+    order: list[LTSNode] = []
+    visited: set[LTSNode] = {lts.start}
+    queue: deque[LTSNode] = deque([lts.start])
+    while queue:
+        node = queue.popleft()
+        order.append(node)
+        successors = [
+            e.target for e in lts.edges
+            if e.source == node and e.target not in visited
+        ]
+        visited.update(successors)
+        queue.extend(successors)
+    return order

clankloop/runner.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Pipeline runner — registers and executes compiled pipelines.
+
+The runner is a thin registry. Execution is a two-step funnel: the caller
+supplies a bare-name parameter dict, :meth:`Pipeline.bind` translates
+and validates it against the compiler-built parameter model (writing resolved
+values into the env), then :meth:`ExecutionGraph.execute` walks the graph
+against the now-bound environment. The graph never sees bare parameter names.
+"""
+
+
+from dataclasses import dataclass, field
+from typing import Mapping
+
+import clankloop.core.graph as graph
+from clankloop.core.env import EnvPath, data_dependencies
+from clankloop.core.errors import (
+    MissingParameterError,
+    UnknownParameterError,
+)
+from clankloop.core.graph import analyze
+from clankloop.plantuml import generate_plantuml
+
+
+@dataclass(frozen=True)
+class ParameterBinding:
+    """A declared parameter and where it lives in the environment.
+
+    The compiler builds one binding per declared ``ParameterSpec`` using the
+    version-folder path builders, pre-resolving the env path so the
+    runtime never constructs namespace-aware paths. :meth:`Pipeline.bind`
+    consumes these to translate caller-facing bare names to env writes,
+    enforce ``required``, and inject ``default`` values.
+
+    Attributes:
+        name: The bare parameter name (the caller-facing contract).
+        path: The pre-resolved env path where the parameter's ``Value`` lives.
+        required: If True, ``bind`` raises ``MissingParameterError`` when no
+            value is supplied.
+        default: If set and no value is supplied, injected by ``bind``.
+    """
+
+    name: str
+    path: EnvPath
+    required: bool = False
+    default: str | None = None
+
+
+@dataclass(frozen=True)
+class Pipeline:
+    """A compiled pipeline ready for execution.
+
+    Attributes:
+        name: The pipeline name.
+        graph: The execution graph containing tasks, actions, and environment.
+        entry_task: The name of the first task to execute.
+        parameters: Compiler-built parameter model — one binding per declared
+            parameter, with pre-resolved env paths. Consumed by ``bind``.
+    """
+
+    name: str
+    graph: graph.ExecutionGraph
+    entry_task: str
+    parameters: tuple[ParameterBinding, ...] = field(default_factory=tuple)
+
+    def consumes(self) -> dict[str, frozenset[str]]:
+        """Env paths each task transitively reads, keyed by task name.
+
+        A static data-flow summary: for every task, the env paths whose
+        evaluation is triggered when the task's command runs — first-order
+        template identifiers and export key-paths, closed through immutable
+        render values. Independent of branch, so it is a fact about the task,
+        not the path taken through the graph.
+        """
+        return {
+            name: data_dependencies(self.graph.env, execution.consumes())
+            for name, execution in self.graph.execs.items()
+        }
+
+    def bind(self, supplied: dict[str, str]) -> None:
+        """Bind caller-supplied parameter values into the graph's environment.
+
+        The single funnel where caller-facing bare names become resolved env
+        writes. For each declared parameter: if supplied, write the value at
+        its pre-resolved path; if not supplied and required, raise; if not
+        supplied and a default exists, inject the default; otherwise leave
+        the slot unassigned (the existing env state).
+
+        Args:
+            supplied: Mapping of bare parameter names to string values, as
+                produced by the CLI (``-p KEY=VALUE`` or taskcar stdin JSON).
+
+        Raises:
+            UnknownParameterError: A supplied name is not a declared parameter.
+            MissingParameterError: A required parameter was not supplied.
+        """
+        bindings = {b.name: b for b in self.parameters}
+
+        for name in supplied:
+            if name not in bindings:
+                raise UnknownParameterError(
+                    f"Parameter {name!r} is not declared in pipeline {self.name!r}; "
+                    f"declared: {sorted(bindings) or '(none)'}"
+                )
+
+        for binding in self.parameters:
+            if binding.name in supplied:
+                self.graph.env.set_value(binding.path, supplied[binding.name])
+            elif binding.required:
+                raise MissingParameterError(
+                    f"Required parameter {binding.name!r} not supplied for "
+                    f"pipeline {self.name!r}"
+                )
+            elif binding.default is not None:
+                self.graph.env.set_value(binding.path, binding.default)
+
+
+class Runner:
+    """Registry and executor for compiled pipelines.
+
+    Pipelines are registered by name and can then be executed or inspected.
+    """
+
+    def __init__(self) -> None:
+        self._pipelines: dict[str, Pipeline] = {}
+
+    def register(self, pipeline: Pipeline) -> None:
+        """Register a compiled pipeline by its name."""
+        self._pipelines[pipeline.name] = pipeline
+
+    def run(
+        self,
+        name: str,
+        parameters: dict[str, str],
+        *,
+        environ: Mapping[str, str],
+        io: graph.IOChannels | None = None,
+        interactive: bool = False,
+    ) -> None:
+        """Execute a registered pipeline by name.
+
+        Funnels the caller-supplied bare-name parameter dict through
+        :meth:`Pipeline.bind` (translate, enforce required, inject
+        defaults), then walks the graph against the bound environment.
+
+        Args:
+            name: The registered pipeline name.
+            parameters: Mapping of bare parameter names to string values.
+            environ: Base process environment forwarded to the graph; the
+                CLI supplies ``os.environ`` at the boundary.
+            io: CLI-owned streams the core tees subprocess output through.
+            interactive: When set, tasks that capture no stdio inherit the
+                tty.
+
+        Raises:
+            ValueError: If no pipeline with *name* has been registered.
+            UnknownParameterError: A supplied parameter is not declared.
+            MissingParameterError: A required parameter was not supplied.
+        """
+        pipeline = self._pipelines.get(name)
+        if pipeline is None:
+            raise ValueError(f"Pipeline {name!r} has not been registered")
+
+        pipeline.bind(parameters)
+        pipeline.graph.execute(
+            pipeline.entry_task,
+            environ=environ,
+            io=io,
+            interactive=interactive,
+        )
+
+    def to_plantuml(self, name: str) -> str:
+        """Render a registered pipeline's execution graph as PlantUML.
+
+        Args:
+            name: The registered pipeline name.
+
+        Returns:
+            A PlantUML activity diagram string.
+
+        Raises:
+            ValueError: If no pipeline with *name* has been registered.
+        """
+        pipeline = self._pipelines.get(name)
+        if pipeline is None:
+            raise ValueError(f"Pipeline {name!r} has not been registered")
+
+        return generate_plantuml(analyze(pipeline.graph, pipeline.entry_task))

clankloop/tracer.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""Tracing facade — proxies to OpenTelemetry when available, no-op otherwise.
+
+This module provides a unified :class:`Tracer` that works whether or not
+OpenTelemetry is installed. When OTel is present, spans are forwarded to the
+real tracer; when it is absent, a silent :class:`DummySpan` is used instead.
+"""
+
+
+from contextlib import contextmanager
+from typing import Any, Iterator
+
+# Try to parse OpenTelemetry core APIs at module level
+try:
+    from opentelemetry import trace as otel_trace
+    HAS_OTEL_TRACE = True
+except ImportError:
+    HAS_OTEL_TRACE = False
+
+
+class DummySpan:
+    """A safe, silent surrogate for an OpenTelemetry Span."""
+
+    def set_attribute(self, key: str, value: Any) -> "DummySpan":
+        return self
+
+    def set_attributes(self, attributes: dict[str, Any]) -> "DummySpan":
+        return self
+
+    def record_exception(self, exception: Exception) -> "DummySpan":
+        return self
+
+    def set_status(self, status: Any) -> "DummySpan":
+        return self
+
+
+class Tracer:
+    """A facade managing tracing.
+
+    If OpenTelemetry is installed, it proxies to the real OTel tracer.
+    If not, it acts as a silent, safe no-op.
+    """
+
+    def __init__(self, name: str):
+        self.name = name
+        self._otel_tracer = None
+        if HAS_OTEL_TRACE:
+            self._otel_tracer = otel_trace.get_tracer(name)
+
+    @contextmanager
+    def start_as_current_span(
+        self,
+        name: str,
+        attributes: dict[str, Any] | None = None,
+    ) -> Iterator[Any]:
+        """Context manager that starts a span and yields it.
+
+        When OpenTelemetry is active, a real span is created and made current.
+        Otherwise, a :class:`DummySpan` is yielded.
+
+        Args:
+            name: The span name.
+            attributes: Optional attributes to attach to the span.
+
+        Yields:
+            The active span (real or dummy).
+        """
+        if HAS_OTEL_TRACE and self._otel_tracer:
+            with self._otel_tracer.start_as_current_span(name) as span:
+                if attributes:
+                    span.set_attributes(attributes)
+                yield span
+        else:
+            yield DummySpan()

clankloop-0.0.0.dist-info/METADATA

@@ -0,0 +1,20 @@
+Metadata-Version: 2.5
+Name: clankloop
+Version: 0.0.0
+Summary: Build deterministic loops with clankers.
+Author-email: Caj Larsson <polsent@caj.me>
+License-Expression: GPL-3.0-only
+License-File: LICENSE
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.13
+Requires-Dist: cattrs>=23.0.0
+Requires-Dist: pyyaml>=6.0.3
+Description-Content-Type: text/markdown
+
+# Clank Loop
+
+# Ideas
+
+