whiletrue 0.1.0__py3-none-any.whl

whiletrue/core/caps.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, ValidationError
+
+
+class CapError(Exception):
+    """Caps are named schemas attached to ports (like GStreamer caps)."""
+
+
+@dataclass
+class CapValidation:
+    ok: bool
+    value: Any = None
+    errors: list[str] = field(default_factory=lambda: [])
+
+
+_CAP_NAME = re.compile(r"^[A-Z][A-Za-z0-9]*$")
+
+
+def format_validation_error(error: ValidationError) -> list[str]:
+    """`path: message` per issue, in the order pydantic reports them."""
+    out: list[str] = []
+    for issue in error.errors():
+        path = ".".join(str(p) for p in issue["loc"])
+        out.append(f"{path}: {issue['msg']}" if path else issue["msg"])
+    return out
+
+
+class CapRegistry:
+    def __init__(self) -> None:
+        self._caps: dict[str, TypeAdapter[Any]] = {}
+
+    def register(self, name: str, schema: Any) -> None:
+        """`schema` is anything pydantic can validate: a model class, `str`, `Any`, ..."""
+        if not _CAP_NAME.match(name):
+            raise CapError(f'Invalid cap name "{name}" (use PascalCase)')
+        if name in self._caps:
+            raise CapError(f'Cap "{name}" is already registered')
+        self._caps[name] = schema if isinstance(schema, TypeAdapter) else TypeAdapter(schema)  # pyright: ignore[reportUnknownVariableType]
+
+    def has(self, name: str) -> bool:
+        return name in self._caps
+
+    def names(self) -> list[str]:
+        return list(self._caps)
+
+    def _get(self, name: str) -> TypeAdapter[Any]:
+        adapter = self._caps.get(name)
+        if adapter is None:
+            raise CapError(f'Unknown cap "{name}"')
+        return adapter
+
+    def validate(self, name: str, value: Any) -> CapValidation:
+        adapter = self._get(name)
+        try:
+            parsed = adapter.validate_python(value)
+        except ValidationError as error:
+            return CapValidation(ok=False, errors=format_validation_error(error))
+        return CapValidation(ok=True, value=adapter.dump_python(parsed, mode="json", by_alias=True))
+
+    def to_json_schema(self, name: str) -> dict[str, Any]:
+        return self._get(name).json_schema()
+
+    def compatible(self, from_cap: str, to_cap: str) -> bool:
+        """Can a value produced under `from_cap` be consumed under `to_cap`?
+
+        Nominal: identical caps, or either side is `Any`. Unknown caps are never compatible.
+        """
+        if not self.has(from_cap) or not self.has(to_cap):
+            return False
+        return "Any" in (from_cap, to_cap) or from_cap == to_cap
+
+
+class _Strict(BaseModel):
+    model_config = ConfigDict(strict=True, populate_by_name=True)
+
+
+class Issue(_Strict):
+    id: str | int
+    number: int | None = None
+    title: str
+    body: str
+    labels: list[str] | None = None
+    url: str | None = None
+    spec_refs: list[str] | None = None
+    depends_on: list[str | int] | None = None
+
+
+class DiffFile(_Strict):
+    path: str
+    additions: int
+    deletions: int
+
+
+class Diff(_Strict):
+    files: list[DiffFile]
+    patch: str | None = None
+
+
+class PullRequest(_Strict):
+    number: int
+    url: str
+    branch: str
+    base: str | None = None
+    title: str | None = None
+    repo: str | None = None
+
+
+class Verdict(_Strict):
+    pass_: bool = Field(alias="pass")
+    reason: str | None = None
+
+
+class Finding(_Strict):
+    file: str | None = None
+    line: int | None = None
+    kind: str | None = None
+    severity: Literal["low", "medium", "high", "critical"]
+    message: str
+
+
+class ReviewFindings(_Strict):
+    findings: list[Finding]
+
+
+def create_builtin_caps() -> CapRegistry:
+    caps = CapRegistry()
+    caps.register("Any", Any)
+    caps.register("Text", str)
+    caps.register("Issue", Issue)
+    caps.register("Diff", Diff)
+    caps.register("PullRequest", PullRequest)
+    caps.register("Verdict", Verdict)
+    caps.register("ReviewFindings", ReviewFindings)
+    return caps

whiletrue/core/comments.py

@@ -0,0 +1,80 @@
+"""Comments are human (or reviewer) input attached to an item; every one must get an answer.
+
+Providers fetch comments from wherever they live (GitHub PR threads, a local file) and post
+replies. The store remembers them across runs, so a comment is answered once.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal, Protocol
+
+from whiletrue.core.history import CommentRecord
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from whiletrue.core.registry import Registry
+    from whiletrue.core.store import StateStore
+
+#: Prefix on every reply the pipeline posts, so people always know who wrote what.
+REPLY_PREFIX = "[whiletrue]"
+
+
+@dataclass(frozen=True)
+class IncomingComment:
+    external_id: str
+    author: str
+    body: str
+    created_at: int
+    thread: str | None = None
+    url: str | None = None
+    kind: Literal["human", "reviewer"] = "human"
+
+
+@dataclass
+class CommentsContext:
+    cwd: str
+    now: Callable[[], int]
+    item_id: str
+    item: dict[str, Any]
+    #: What the step before the gate produced (for GitHub: the opened PR).
+    input: Any = None
+
+
+class CommentsProvider(Protocol):
+    """Where comments come from and where replies go. Providers never resolve threads."""
+
+    async def fetch(self, ctx: CommentsContext) -> list[IncomingComment]: ...
+
+    async def reply(self, comment: CommentRecord, body: str, ctx: CommentsContext) -> str | None:
+        """Posts a reply in the comment's thread; returns the new comment's id if there is one."""
+        ...
+
+
+def with_prefix(body: str) -> str:
+    return body if body.startswith(REPLY_PREFIX) else f"{REPLY_PREFIX} {body}"
+
+
+async def sync_comments(
+    registry: Registry, store: StateStore, ctx: CommentsContext
+) -> list[CommentRecord]:
+    """Pulls new comments from every provider into the store; returns the ones just added."""
+    added: list[CommentRecord] = []
+    for name, provider in registry.providers("comments"):
+        incoming = await provider.fetch(ctx)
+        for comment in incoming:
+            record = store.add_comment(
+                item_id=ctx.item_id,
+                source=name,
+                external_id=comment.external_id,
+                author=comment.author,
+                body=comment.body,
+                created_at=comment.created_at,
+                thread=comment.thread,
+                url=comment.url,
+                kind=comment.kind,
+            )
+            if record is not None:
+                added.append(record)
+    return added

whiletrue/core/composite.py

@@ -0,0 +1,140 @@
+"""Composite expansion: `composite: { uses: <file>, params: {...} }` becomes a `sequence` node
+holding the composite's steps, with `{{params.x}}` filled in. Done at load time, so validation,
+planning and hashing see the real tree."""
+
+from __future__ import annotations
+
+import copy
+import re
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from whiletrue.core.config import (
+    CompositeDefinition,
+    ConfigError,
+    PipelineNode,
+    SourceLoc,
+    load_composite,
+)
+from whiletrue.core.template import render_template
+
+MAX_DEPTH = 10
+RECIPE_PREFIX = "recipe:"
+RECIPES_DIR = Path(__file__).resolve().parent.parent / "recipes"
+
+_PARAM = re.compile(r"\{\{\s*params\.([A-Za-z_][A-Za-z0-9_-]*)\s*\}\}")
+
+
+class _CompositeStep(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    uses: str = Field(min_length=1)
+    params: dict[str, Any] = Field(default_factory=lambda: {})
+
+
+def _resolve_path(uses: str, base_dir: Path, loc: SourceLoc) -> Path:
+    if uses.startswith(RECIPE_PREFIX):
+        path = RECIPES_DIR / f"{uses[len(RECIPE_PREFIX) :]}.yaml"
+        if not path.is_file():
+            raise ConfigError(loc, f'Unknown recipe "{uses[len(RECIPE_PREFIX) :]}"')
+        return path
+    path = (base_dir / uses).resolve()
+    if not path.is_file():
+        raise ConfigError(loc, f"Composite file not found: {uses}")
+    return path
+
+
+def _bind_params(
+    definition: CompositeDefinition, given: dict[str, Any], loc: SourceLoc
+) -> dict[str, Any]:
+    unknown = sorted(set(given) - set(definition.params))
+    if unknown:
+        known = ", ".join(sorted(definition.params)) or "none"
+        raise ConfigError(
+            loc, f'Unknown param "{unknown[0]}" for composite "{definition.name}" (known: {known})'
+        )
+    bound: dict[str, Any] = {}
+    for name, spec in definition.params.items():
+        if name in given:
+            bound[name] = given[name]
+        elif spec.required:
+            raise ConfigError(loc, f'Composite "{definition.name}" needs param "{name}"')
+        else:
+            bound[name] = spec.default
+    return bound
+
+
+def _substitute(value: Any, params: dict[str, Any], loc: SourceLoc) -> Any:
+    """Fills `{{params.x}}`; a string that is exactly one token keeps the param's own type."""
+    if isinstance(value, str):
+        whole = _PARAM.fullmatch(value.strip())
+        if whole:
+            return _param(whole.group(1), params, loc)
+        return _PARAM.sub(
+            lambda m: render_template("{{v}}", {"v": _param(m.group(1), params, loc)}), value
+        )
+    if isinstance(value, list):
+        return [_substitute(v, params, loc) for v in value]  # pyright: ignore[reportUnknownVariableType]
+    if isinstance(value, dict):
+        return {k: _substitute(v, params, loc) for k, v in value.items()}  # pyright: ignore[reportUnknownVariableType]
+    return value
+
+
+def _param(name: str, params: dict[str, Any], loc: SourceLoc) -> Any:
+    if name not in params:
+        raise ConfigError(loc, f'Unknown param "{name}"')
+    return copy.deepcopy(params[name])
+
+
+def _prepare(node: PipelineNode, prefix: str, params: dict[str, Any]) -> None:
+    node.config = _substitute(node.config, params, node.loc)
+    node.id = f"{prefix}.{node.id}"
+    node.wires = {port: f"{prefix}.{target}" for port, target in node.wires.items()}
+    if node.use == "switch":  # `switch` names sibling steps in its config; keep them in sync
+        cases = node.config.get("cases")
+        if isinstance(cases, dict):
+            node.config["cases"] = {k: f"{prefix}.{v}" for k, v in cases.items()}  # pyright: ignore[reportUnknownVariableType]
+        if isinstance(node.config.get("default"), str):
+            node.config["default"] = f"{prefix}.{node.config['default']}"
+    for child in node.children:
+        _prepare(child, prefix, params)
+
+
+def expand_composites(
+    node: PipelineNode, base_dir: Path, sources: list[str], stack: tuple[Path, ...] = ()
+) -> PipelineNode:
+    """Returns `node` with every `composite` step replaced by its expansion (recursively)."""
+    if node.use != "composite":
+        node.children = [expand_composites(c, base_dir, sources, stack) for c in node.children]
+        return node
+    try:
+        step = _CompositeStep.model_validate(node.config)
+    except ValidationError as error:
+        raise ConfigError(
+            node.loc, f"Invalid composite step: {error.errors()[0]['msg']}"
+        ) from error
+    path = _resolve_path(step.uses, base_dir, node.loc)
+    if path in stack:
+        raise ConfigError(
+            node.loc, f"Composite cycle: {' -> '.join(p.name for p in (*stack, path))}"
+        )
+    if len(stack) >= MAX_DEPTH:
+        raise ConfigError(node.loc, f"Composites nested deeper than {MAX_DEPTH} levels")
+    definition = load_composite(path)
+    params = _bind_params(definition, step.params, node.loc)
+    inner = definition.root
+    _prepare(inner, node.id, params)
+    if str(path) not in sources and not str(path).startswith(str(RECIPES_DIR)):
+        sources.append(str(path))
+    expanded = expand_composites(inner, path.parent, sources, (*stack, path))
+    return PipelineNode(
+        id=node.id,
+        use="sequence",
+        config={},
+        children=[expanded],
+        wires=node.wires,
+        loc=node.loc,
+        ports=definition.ports or None,
+    )