roadie 0.1.0__tar.gz

roadie-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+
+      # The hosted images' preinstalled rustup and stable toolchain serve the
+      # Cargo tests.
+      - run: uv sync --locked
+      - run: uv run ruff check
+      - run: uv run mypy src
+      - run: uv run pytest

roadie-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - run: uv build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: distributions
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

roadie-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+/.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+/build/
+/dist/
+/target/

roadie-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sasha Ovsankin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

roadie-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: roadie
+Version: 0.1.0
+Summary: Wire up multi-language, incremental builds in a few lines of Python.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: cyclopts<5.0.0,>=4.20.0
+Requires-Dist: python-dotenv<2.0.0,>=1.2.1
+Description-Content-Type: text/markdown
+
+# Roadie
+
+Wire up multi-language, incremental builds in a few lines of Python.
+
+A step that does not need to run does not run. Roadie knows each step's
+inputs, so when they are unchanged since the step last succeeded, it reuses
+that result instead of running the step; a step whose result cannot be
+reused, such as a fuzzing run, says so.
+
+Like a roadie on stage, it sets up and connects the native tools (cargo,
+pnpm, uv) and lets them play, instead of replacing them.
+
+## Install
+
+```sh
+uv add roadie
+uvx roadie
+```
+
+## A two-step build file
+
+`roadie` runs the last step defined in `<directory>/build.py`, after the
+steps it depends on. The second run reuses a step whose inputs have not
+changed.
+
+```python
+from dataclasses import dataclass
+from pathlib import Path
+
+from roadie import *
+from roadie.run import Run
+
+
+@dataclass(eq=False)
+class Emitter(File):
+    text: str = "hello"
+
+    def build(self, run: Run) -> Path:
+        path = run.artifact(self, ".txt")
+        path.write_text(self.text)
+        return path
+
+
+@dataclass(eq=False)
+class Copy(File):
+    source: File
+
+    def build(self, run: Run) -> Path:
+        path = run.artifact(self, ".txt")
+        path.write_text(run[self.source].read_text())
+        return path
+
+
+api = Emitter()
+copy = Copy(api)
+```
+
+```sh
+roadie .
+```
+
+The design is in [docs/spec.md](docs/spec.md).

roadie-0.1.0/README.md

@@ -0,0 +1,62 @@
+# Roadie
+
+Wire up multi-language, incremental builds in a few lines of Python.
+
+A step that does not need to run does not run. Roadie knows each step's
+inputs, so when they are unchanged since the step last succeeded, it reuses
+that result instead of running the step; a step whose result cannot be
+reused, such as a fuzzing run, says so.
+
+Like a roadie on stage, it sets up and connects the native tools (cargo,
+pnpm, uv) and lets them play, instead of replacing them.
+
+## Install
+
+```sh
+uv add roadie
+uvx roadie
+```
+
+## A two-step build file
+
+`roadie` runs the last step defined in `<directory>/build.py`, after the
+steps it depends on. The second run reuses a step whose inputs have not
+changed.
+
+```python
+from dataclasses import dataclass
+from pathlib import Path
+
+from roadie import *
+from roadie.run import Run
+
+
+@dataclass(eq=False)
+class Emitter(File):
+    text: str = "hello"
+
+    def build(self, run: Run) -> Path:
+        path = run.artifact(self, ".txt")
+        path.write_text(self.text)
+        return path
+
+
+@dataclass(eq=False)
+class Copy(File):
+    source: File
+
+    def build(self, run: Run) -> Path:
+        path = run.artifact(self, ".txt")
+        path.write_text(run[self.source].read_text())
+        return path
+
+
+api = Emitter()
+copy = Copy(api)
+```
+
+```sh
+roadie .
+```
+
+The design is in [docs/spec.md](docs/spec.md).

roadie-0.1.0/docs/spec.md

@@ -0,0 +1,107 @@
+# Roadie
+
+## Goal
+
+A step that does not need to run does not run. Roadie knows each step's
+inputs, so when they are unchanged since the step last succeeded, it reuses
+that result instead of running the step; a step whose result cannot be
+reused, such as a fuzzing run, says so. Everything else in this spec serves
+that goal.
+
+**Roadie**: "Wire up multi-language, incremental builds in a
+few lines of Python." Like a roadie on stage, it sets up and connects the
+native tools (cargo, pnpm, uv) and lets them play, instead of replacing
+them.
+
+## Concepts
+
+Roadie defines and executes graphs of steps.
+
+- Job: a directed acyclic graph of connected steps.
+- Step: a class whose `build(run)` produces a value and whose
+  `teardown(value)` releases it. Attributes that are steps declare dependencies.
+- Run: one execution of a plan. `run[step]` is a dependency's value;
+  `run.artifact(step, suffix)` names a file under `target/roadie/`.
+- Result: the value a step produces. Kinds: `Binary` and `File` produce
+  paths, `Service` produces a running deployment, and `Tests` produces
+  `TestResults` containing failing test names and messages plus log messages.
+  Any failing test fails its step.
+
+The executor builds dependencies first and tears down each step immediately
+following its last consumer in the plan. On failure, SIGTERM or Ctrl-C it
+tears down the remaining steps in reverse order. A failed step names itself
+and its reason; a command failure includes the command, exit status and end
+of stderr.
+
+`CargoPackage(name)` names one crate by its Cargo name. Its input set is
+the crate's local dependency closure.
+A binary is fingerprinted from its inputs, not its bytes.
+
+## User experience
+
+```
+roadie [--dry-run | --dry] [--locked] [--base_dir DIR] [directory] [result]
+```
+
+- A build file is `<directory>/build.py`: Python step instances assigned to
+  variables. It starts with `from roadie import *`.
+- Loading a build file constructs its steps and runs none. Roadie loads it
+  with `runpy`, so the file's directory is not on `sys.path`.
+- `result` names a variable of the build file. Without it, Roadie selects the
+  step instantiated last. Reassigning a name does not move its original step.
+- `include(directory)` loads `<directory>/build.py`, relative to the
+  including file, once per load, and returns its steps by variable name.
+  Included steps are named `<directory>:<name>`.
+- A result needs only its dependencies: `api` builds the server and generates
+  the contract without deploying it. `--dry-run` (`--dry`) prints the plan
+  and runs none.
+- Commands belong in step classes and Roadie utilities. `Step._cmd` echoes
+  and runs a command; `Step._start_cmd` starts a process, waits for its port,
+  and returns a `RunningProcess` to stop at teardown.
+
+## Enforcing declared inputs
+
+Planned; not implemented.
+
+A missing declaration has one of two effects:
+
+- An input the step receives through its signature (a path, a value, an
+  environment variable, an earlier step's Output) is simply absent, and the
+  step fails.
+- An input the step finds in the working tree is still on disk, so the step
+  passes and the fingerprint misses it. A later run replays a stale verdict.
+
+`Files` separates a step's code (its tests and scripts) from the data it
+checks: `Files(code=..., data=...)`. Undeclared reads enter through code
+changes, such as a new test that opens a new file.
+
+Enforcement runs, with the cache off, in two situations:
+
+- nightly, for every step;
+- on a change to Roadie or to the step definitions (all steps), or to a
+  step's code inputs (that step).
+
+An enforcement run uses either of two modes:
+
+- Restricted tree: the step runs in a directory holding only its declared
+  inputs, its Outputs-as-Inputs, and its toolchain environment. It catches a
+  read of a named file. A step that enumerates files can pass on the smaller
+  tree.
+- Read tracing: the step runs in the full checkout under a file-access
+  tracer, and any read outside its declared inputs fails it. It catches
+  enumeration too. Linux only for now.
+
+When an enforcement run finds an undeclared read, it fails and names the step
+and the file. Every cached verdict for that step since the last clean
+enforcement run becomes unverified, so the next run executes the step again.
+Between enforcement runs, a missing declaration can replay a stale verdict
+for that one step for at most a day.
+
+## Backlog
+
+- `AuthorTask`: a `Tests` step that waits for the author to run checks and
+  report the results.
+- `AuthorApproval`: an author task that continues the run or cancels it.
+- Enforce declared inputs (the design above).
+- A project-root override (`config(root=...)`) when a project's root is not
+  its git top level.

roadie-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "roadie"
+version = "0.1.0"
+description = "Wire up multi-language, incremental builds in a few lines of Python."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.13"
+dependencies = [
+    "cyclopts>=4.20.0,<5.0.0",
+    "python-dotenv>=1.2.1,<2.0.0",
+]
+
+[project.scripts]
+roadie = "roadie.cli:main"
+
+[dependency-groups]
+dev = [
+    "mypy",
+    "pytest",
+    "ruff",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/roadie"]

roadie-0.1.0/src/roadie/__init__.py

@@ -0,0 +1,27 @@
+from roadie.cargo import CargoPackage
+from roadie.config import config
+from roadie.errors import RoadieError
+from roadie.graph import include
+from roadie.inputs import Files
+from roadie.step import Binary, Deployment, File, HttpService, Service, Step, Tests
+from roadie.steps import Group, RustBinary
+from roadie.testing import TestFailure, TestResults
+
+__all__ = [
+    "Binary",
+    "CargoPackage",
+    "Deployment",
+    "File",
+    "Files",
+    "Group",
+    "HttpService",
+    "RoadieError",
+    "RustBinary",
+    "Service",
+    "Step",
+    "TestFailure",
+    "TestResults",
+    "Tests",
+    "config",
+    "include",
+]

roadie-0.1.0/src/roadie/cargo.py

@@ -0,0 +1,205 @@
+"""Cargo workspace packages and the local dependency closure."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+from collections.abc import Iterator, Sequence
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from pathlib import Path
+
+from roadie.errors import RoadieError
+from roadie.inputs import Input, digest
+
+_CARGO_ENV_EXACT = frozenset({"RUSTFLAGS", "RUSTDOCFLAGS", "CARGO_ENCODED_RUSTFLAGS"})
+_CARGO_ENV_PREFIXES = ("CARGO_PROFILE_", "CARGO_BUILD_")
+_ROOT_FILES = ("Cargo.toml", "Cargo.lock", "rust-toolchain.toml", ".cargo/config.toml")
+_cache: ContextVar[dict[Path, CargoSnapshot] | None] = ContextVar(
+    "roadie_cargo_snapshot", default=None
+)
+
+
+@dataclass(frozen=True)
+class RustPackage:
+    name: str
+    root: Path
+    local_dependencies: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class CargoWorkspace:
+    root: Path
+    packages: tuple[RustPackage, ...]
+
+
+def cargo_rust_packages(directory: Path) -> CargoWorkspace:
+    result = subprocess.run(
+        ("cargo", "metadata", "--no-deps", "--format-version", "1"),
+        cwd=directory,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    metadata = json.loads(result.stdout)
+    root = Path(metadata["workspace_root"]).resolve()
+    workspace_names = {package["name"] for package in metadata["packages"]}
+    packages = []
+    for package in metadata["packages"]:
+        manifest = Path(package["manifest_path"])
+        try:
+            package_root = manifest.parent.resolve().relative_to(root)
+        except ValueError:
+            continue
+        local_dependencies = tuple(
+            dependency["name"]
+            for dependency in package["dependencies"]
+            if dependency["name"] in workspace_names
+        )
+        packages.append(RustPackage(package["name"], package_root, local_dependencies))
+    return CargoWorkspace(root, tuple(packages))
+
+
+def select_rust_packages(
+    packages: Sequence[RustPackage],
+    changed_paths: Sequence[Path],
+) -> tuple[str, ...]:
+    """Packages whose files changed, plus every workspace package that depends on them."""
+    if any(path.as_posix() in {"Cargo.toml", "Cargo.lock"} for path in changed_paths):
+        return tuple(package.name for package in packages)
+
+    selected = {
+        package.name
+        for package in packages
+        if any(
+            path == package.root or package.root in path.parents
+            for path in changed_paths
+        )
+    }
+    changed = True
+    while changed:
+        changed = False
+        for package in packages:
+            if package.name in selected:
+                continue
+            if selected.intersection(package.local_dependencies):
+                selected.add(package.name)
+                changed = True
+    return tuple(package.name for package in packages if package.name in selected)
+
+
+@dataclass(frozen=True)
+class CargoSnapshot:
+    workspace: CargoWorkspace
+    rustc: str
+
+
+@contextmanager
+def cargo_snapshot() -> Iterator[None]:
+    """Reuse cargo metadata and rustc --version for every fingerprint in the block."""
+    token = _cache.set({})
+    try:
+        yield
+    finally:
+        _cache.reset(token)
+
+
+def _load_snapshot(directory: Path) -> CargoSnapshot:
+    version = subprocess.run(
+        ("rustc", "--version"),
+        cwd=directory,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return CargoSnapshot(cargo_rust_packages(directory), version.stdout.strip())
+
+
+def _snapshot(directory: Path) -> CargoSnapshot:
+    directory = directory.resolve()
+    current = _cache.get()
+    if isinstance(current, dict):
+        cached = _cached_snapshot(current, directory)
+        if cached is not None:
+            return cached
+    loaded = _load_snapshot(directory)
+    if isinstance(current, dict):
+        current.setdefault(loaded.workspace.root, loaded)
+        return current[loaded.workspace.root]
+    return loaded
+
+
+def _cached_snapshot(
+    cache: dict[Path, CargoSnapshot], directory: Path
+) -> CargoSnapshot | None:
+    for root, snapshot in cache.items():
+        if directory.is_relative_to(root):
+            return snapshot
+    return None
+
+
+def _cargo_environment() -> dict[str, str]:
+    return {
+        key: value
+        for key, value in sorted(os.environ.items())
+        if key in _CARGO_ENV_EXACT or key.startswith(_CARGO_ENV_PREFIXES)
+    }
+
+
+def _closure(packages: Sequence[RustPackage], name: str) -> tuple[RustPackage, ...]:
+    by_name = {package.name: package for package in packages}
+    if name not in by_name:
+        raise RoadieError(f"cargo package {name!r} is not in the workspace")
+    selected: set[str] = set()
+    pending = [name]
+    while pending:
+        current = pending.pop()
+        if current in selected:
+            continue
+        selected.add(current)
+        pending.extend(by_name[current].local_dependencies)
+    return tuple(package for package in packages if package.name in selected)
+
+
+def _git_files(root: Path, paths: Sequence[str]) -> list[str]:
+    if not paths:
+        return []
+    result = subprocess.run(
+        ["git", "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", *paths],
+        cwd=root,
+        check=True,
+        capture_output=True,
+    )
+    return [item for item in result.stdout.decode().split("\0") if item]
+
+
+def _content(root: Path, relative: str) -> str:
+    path = root / relative
+    if not path.is_file():
+        return "missing"
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+@dataclass(frozen=True)
+class CargoPackage(Input):
+    name: str
+
+    def fingerprint(self, base_dir: Path) -> str:
+        snapshot = _snapshot(base_dir)
+        root = snapshot.workspace.root
+        packages = _closure(snapshot.workspace.packages, self.name)
+        listed = set(_git_files(root, [package.root.as_posix() for package in packages]))
+        for name in _ROOT_FILES:
+            if (root / name).exists():
+                listed.add(name)
+        return digest(
+            {
+                "package": self.name,
+                "rustc": snapshot.rustc,
+                "env": _cargo_environment(),
+                "files": {path: _content(root, path) for path in listed},
+            }
+        )

roadie-0.1.0/src/roadie/cli.py

@@ -0,0 +1,92 @@
+"""Run a result of a Roadie build file and the steps it depends on."""
+
+from collections.abc import Sequence
+from dataclasses import fields, is_dataclass
+from pathlib import Path
+from typing import Annotated, Any
+
+from cyclopts import App, Parameter
+
+from roadie.graph import RoadieError, load
+from roadie.run import execute, reuse_markers
+from roadie.step import Step
+from roadie.steps import Group
+
+app = App(help=__doc__, version_flags=())
+
+
+@app.default
+def run(
+    directory: Path = Path("."),
+    result: str | None = None,
+    *,
+    base_dir: Annotated[Path | None, Parameter(name="--base_dir", help="Resolve step paths and commands from this directory")] = None,
+    locked: Annotated[bool, Parameter(negative=False, help="Fail when generated tracked files would change")] = False,
+    env: Annotated[
+        Sequence[Path] | None,
+        Parameter(name="--env", help="KEY=VALUE environment file; may be repeated", negative=False),
+    ] = None,
+    dry_run: Annotated[
+        bool,
+        Parameter(
+            name=["--dry-run", "--dry"],
+            negative=False,
+            help="Print the steps the result needs and run none",
+        ),
+    ] = False,
+) -> None:
+    """Run `result` of `<directory>/build.py`, by default the last one defined."""
+    try:
+        graph = load(directory, base_dir=base_dir)
+        steps = graph.plan(result)
+    except RoadieError as error:
+        raise SystemExit(str(error)) from error
+    if dry_run:
+        try:
+            marks = reuse_markers(steps, root=graph.root, env=env or ())
+        except RoadieError as error:
+            raise SystemExit(str(error)) from error
+        for step, reused in zip(steps, marks, strict=True):
+            line = f"{step.name} = {call(step)}" if step.name else call(step)
+            print(f"{line}  # {'reuse' if reused else 'run'}")
+        return
+    try:
+        execute(steps, root=graph.root, locked=locked, env=env or ())
+    except RoadieError as error:
+        raise SystemExit(str(error)) from error
+
+
+def call(result: Step[Any]) -> str:
+    if isinstance(result, Group):
+        arguments = [argument(value) for value in result.steps]
+    else:
+        attributes = result.attributes()
+        keywords: set[str] = {item.name for item in fields(result) if item.kw_only} if is_dataclass(result) else set()
+        arguments = [
+            argument(value)
+            for key, value in attributes.items()
+            if key not in keywords and value is not None
+        ]
+        arguments.extend(
+            f"{key}={argument(value)}"
+            for key, value in attributes.items()
+            if key in keywords and value is not None
+        )
+    return f"{type(result).__name__}({', '.join(arguments)})"
+
+
+def argument(value: object) -> str:
+    if isinstance(value, Step):
+        return reference(value)
+    if isinstance(value, tuple):
+        items = ", ".join(argument(item) for item in value)
+        return f"({items}{',' if len(value) == 1 else ''})"
+    return repr(value)
+
+
+def reference(result: Step[Any]) -> str:
+    return result.name or call(result)
+
+
+def main() -> None:
+    app()