harmont 0.0.1__py3-none-any.whl

harmont/__init__.py

@@ -0,0 +1,168 @@
+"""harmont — chain-style Python DSL for Harmont CI pipelines.
+
+The whole public surface:
+
+    scratch()                -> Step (root)
+    sh(cmd, **kw)            -> Step  (== scratch().sh(cmd, **kw))
+    Step.sh(cmd, **kw)       -> Step
+    Step.fork(label=None)    -> Step
+    wait(*, continue_on_failure=False) -> Step
+
+    pipeline(*leaves, env=None, default_image=None) -> dict (v0 IR)
+    pipeline_to_json(p, **kw) -> str
+
+    @pipeline(slug, ..., triggers=[...], allow_manual=True)  -> decorator
+    push(branch=..., tag=...)         -> PushTrigger
+    pull_request(branches=..., types=...) -> PullRequestTrigger
+    schedule(cron=...)                 -> ScheduleTrigger
+    dump_registry_json()              -> str  (HAR-9 envelope)
+
+Cache helpers: ttl, on_change, forever, compose.
+
+``hm.pipeline`` is polymorphic. When called with positional ``Step``
+arguments it builds a v0 IR dict (the factory). When called with no
+positionals or a string slug it returns a decorator that registers a
+function as a CI pipeline (HAR-9).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from . import _decorator
+from ._envelope import dump_registry_json
+from ._step import Step, scratch, wait
+from ._target import clear_target_cache, target  # noqa: F401  clear_target_cache used by tests
+from ._typing import BaseImage, Target
+from .cache import (
+    CacheCompose,
+    CacheForever,
+    CacheNone,
+    CacheOnChange,
+    CachePolicy,
+    CacheTTL,
+)
+from .cmake import cmake
+from .composer import composer
+from .dotnet import dotnet
+from .elm import elm
+from .go import go
+from .gradle import gradle
+from .haskell import haskell
+from .npm import npm
+from .ocaml import ocaml
+from .perl import perl
+from .pipeline import pipeline as _pipeline_factory
+from .pipeline import pipeline_to_json
+from .python import python
+from .ruby import ruby
+from .rust import rust
+from .triggers import pull_request, push, schedule
+from .types import Pipeline
+from .zig import zig
+
+if TYPE_CHECKING:
+    from datetime import timedelta
+
+
+def pipeline(*args: Any, **kwargs: Any) -> Any:
+    """Polymorphic entry point.
+
+    - ``pipeline(*leaves, env=..., default_image=...)`` — every
+      positional arg is a :class:`Step`; returns the v0 IR dict (the
+      factory).
+    - ``pipeline(slug=None, *, name=..., triggers=..., allow_manual=...,
+      env=..., default_image=...)`` — no positionals or a string slug;
+      returns a decorator that registers the wrapped function in the
+      module-level :data:`~harmont._registry.REGISTRATIONS` table
+      (HAR-9).
+
+    The discriminant is the *type* of the positional arguments: any
+    non-Step positional (including a string slug, or no positional at
+    all) routes to the decorator path.
+    """
+    if args and all(isinstance(a, Step) for a in args):
+        return _pipeline_factory(*args, **kwargs)
+    return _decorator.pipeline(*args, **kwargs)
+
+
+def ttl(duration: timedelta) -> CacheTTL:
+    return CacheTTL(duration=duration)
+
+
+def on_change(*paths: str) -> CacheOnChange:
+    return CacheOnChange(paths=tuple(paths))
+
+
+def forever(env_keys: tuple[str, ...] = ()) -> CacheForever:
+    return CacheForever(env_keys=env_keys)
+
+
+def compose(*policies: CachePolicy) -> CacheCompose:
+    return CacheCompose(policies=tuple(policies))
+
+
+def sh(
+    cmd: str,
+    *,
+    cwd: str | None = None,
+    label: str | None = None,
+    cache: CachePolicy | None = None,
+    env: dict[str, str] | None = None,
+    timeout_seconds: int | None = None,
+    image: str | None = None,
+    key: str | None = None,
+) -> Step:
+    """Shorthand for ``scratch().sh(cmd, ...)`` — start a chain in one call."""
+    return scratch().sh(
+        cmd,
+        cwd=cwd,
+        label=label,
+        cache=cache,
+        env=env,
+        timeout_seconds=timeout_seconds,
+        image=image,
+        key=key,
+    )
+
+
+__all__ = [
+    "BaseImage",
+    "CacheCompose",
+    "CacheForever",
+    "CacheNone",
+    "CacheOnChange",
+    "CachePolicy",
+    "CacheTTL",
+    "Pipeline",
+    "Step",
+    "Target",
+    "cmake",
+    "compose",
+    "composer",
+    "dotnet",
+    "dump_registry_json",
+    "elm",
+    "forever",
+    "go",
+    "gradle",
+    "haskell",
+    "npm",
+    "ocaml",
+    "on_change",
+    "perl",
+    "pipeline",
+    "pipeline_to_json",
+    "pull_request",
+    "push",
+    "python",
+    "ruby",
+    "rust",
+    "schedule",
+    "scratch",
+    "sh",
+    "target",
+    "ttl",
+    "wait",
+    "zig",
+]

harmont/_decorator.py

@@ -0,0 +1,68 @@
+"""@hm.pipeline decorator — see docs/superpowers/specs/2026-05-10-har-9-imperfect-dsl-design.md."""
+from __future__ import annotations
+
+import re
+from functools import wraps
+from typing import TYPE_CHECKING, Any
+
+from ._deps import call_with_deps, validate_target_signature
+from ._registry import PipelineRegistration, register
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from .triggers import Trigger
+
+_SLUG_RE = re.compile(r"^[a-z][a-z0-9-]{0,63}$")
+
+
+def _validate_slug(slug: str) -> None:
+    if not _SLUG_RE.match(slug):
+        msg = (
+            f"invalid pipeline slug {slug!r}\n"
+            f"  → use lowercase letters, digits, and '-', "
+            f"start with a letter, max 64 chars"
+        )
+        raise ValueError(msg)
+
+
+def pipeline(
+    slug: str | None = None,
+    *,
+    name: str | None = None,
+    triggers: tuple[Trigger, ...] | list[Trigger] = (),
+    allow_manual: bool = True,
+    env: dict[str, str] | None = None,
+    default_image: str | None = None,
+) -> Callable[[Callable[..., Any]], Callable[[], Any]]:
+    """Register a function as a CI pipeline.
+
+    The wrapped function returns a :class:`Step`, a tuple of leaves
+    (:data:`Pipeline`), or any toolchain wrapper that
+    :func:`harmont._unwrap.as_leaves` can coerce. The function may
+    declare dependencies as parameters (pytest-style); each parameter
+    name is resolved against the global target registry.
+    """
+    def decorator(fn: Callable[..., Any]) -> Callable[[], Any]:
+        validate_target_signature(fn)
+        resolved = slug if slug is not None else fn.__name__
+        _validate_slug(resolved)
+
+        @wraps(fn)
+        def wrapper() -> Any:
+            return call_with_deps(fn)
+
+        register(
+            PipelineRegistration(
+                slug=resolved,
+                name=name if name is not None else resolved,
+                triggers=tuple(triggers),
+                allow_manual=allow_manual,
+                env=env,
+                default_image=default_image,
+                fn=wrapper,
+            )
+        )
+        return wrapper
+
+    return decorator

harmont/_deps.py

@@ -0,0 +1,188 @@
+"""Shared dependency resolution for @hm.target and @hm.pipeline (HAR-28).
+
+Strict-marker model:
+- ``Target[T]``           — resolve by parameter name from the global
+                            target registry; raise if not found.
+- ``BaseImage["X"]``      — inject a scratch-rooted ``Step(image=X)``.
+- plain param with default — bind the default value.
+- anything else            — raise at decoration time via
+                            :func:`validate_target_signature`.
+
+Cycle detection uses a module-level "currently resolving" stack keyed
+by function name; the dump_registry_json render clears it at the
+start of every render along with the target memoization cache.
+"""
+
+from __future__ import annotations
+
+import inspect
+import typing
+from typing import TYPE_CHECKING, Any
+
+from ._step import Step
+from ._typing import _TARGET_MARKER, _BaseImageMarker
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+_TARGETS_BY_NAME: dict[str, Callable[[], Any]] = {}
+_RESOLVING: list[str] = []
+
+
+def register_named_target(name: str, fn: Callable[[], Any]) -> None:
+    """Register a named target. Raises on duplicate name."""
+    if name in _TARGETS_BY_NAME:
+        msg = (
+            f"hm: duplicate target name {name!r}\n"
+            "  → each @hm.target must have a unique name; pass "
+            'name="..." to disambiguate'
+        )
+        raise ValueError(msg)
+    _TARGETS_BY_NAME[name] = fn
+
+
+def clear_target_names() -> None:
+    """Reset the name registry and cycle-detection stack. Used by tests
+    and `clear_target_cache()` (the full reset used at test boundaries)."""
+    _TARGETS_BY_NAME.clear()
+    _RESOLVING.clear()
+
+
+def _param_kind_error(param: inspect.Parameter) -> str | None:
+    """Return a fix-directed error message if `param` has a forbidden kind."""
+    kind = param.kind
+    if kind == inspect.Parameter.VAR_POSITIONAL:
+        return (
+            "hm: target functions cannot take *args\n"
+            "  → declare each dependency as an explicit named parameter"
+        )
+    if kind == inspect.Parameter.VAR_KEYWORD:
+        return (
+            "hm: target functions cannot take **kwargs\n"
+            "  → declare each dependency as an explicit named parameter"
+        )
+    if kind == inspect.Parameter.POSITIONAL_ONLY:
+        return (
+            f"hm: target functions cannot have positional-only "
+            f"parameters (got {param.name!r})\n"
+            "  → remove the '/' marker; parameters must be name-resolvable"
+        )
+    return None
+
+
+def _marker_for(annotation: Any) -> object | None:
+    """Inspect an `Annotated[T, ...]` annotation and return the
+    hm-specific marker (a `_TargetMarker` or `_BaseImageMarker`) if
+    present, else None."""
+    if typing.get_origin(annotation) is None:
+        return None
+    metadata = typing.get_args(annotation)[1:]
+    for meta in metadata:
+        if meta is _TARGET_MARKER:
+            return _TARGET_MARKER  # type: ignore[no-any-return]
+        if isinstance(meta, _BaseImageMarker):
+            return meta
+    return None
+
+
+def _safe_get_type_hints(fn: Callable[..., Any]) -> dict[str, Any]:
+    """`typing.get_type_hints(fn, include_extras=True)` but tolerant of
+    forward references that fail to resolve — fall back to the raw
+    `__annotations__` dict so markers still surface."""
+    try:
+        return typing.get_type_hints(fn, include_extras=True)
+    except Exception:  # intentionally broad; fallback path
+        return dict(getattr(fn, "__annotations__", {}))
+
+
+def validate_target_signature(fn: Callable[..., Any]) -> None:
+    """Decoration-time validation. Raise TypeError on any of:
+
+      - `*args` / `**kwargs` / positional-only parameter.
+      - Parameter with no marker and no default value.
+
+    A parameter with an `hm.Target[T]` or `hm.BaseImage["X"]` marker
+    in its annotation is always valid. A parameter with neither
+    marker but a default value is allowed (the default is used).
+    """
+    sig = inspect.signature(fn)
+    hints = _safe_get_type_hints(fn)
+    for param in sig.parameters.values():
+        kind_err = _param_kind_error(param)
+        if kind_err is not None:
+            raise TypeError(kind_err)
+        annotation = hints.get(param.name)
+        if _marker_for(annotation) is not None:
+            continue
+        if param.default is not inspect.Parameter.empty:
+            continue
+        msg = (
+            f"hm: parameter {param.name!r} has no marker and no default\n"
+            "  → annotate with Target[T] (target dep) or "
+            'BaseImage["..."] (scratch image), or give it a default'
+        )
+        raise TypeError(msg)
+
+
+def resolve_deps(fn: Callable[..., Any]) -> dict[str, Any]:
+    """Walk ``fn``'s signature and produce the kwargs to invoke it.
+
+    Marker dispatch per parameter:
+      - `Target[T]`        → look up param name in `_TARGETS_BY_NAME`;
+                             raise if not found.
+      - `BaseImage["X"]`   → inject `Step(image="X")` (a scratch root).
+      - no marker, default → bind the default value.
+      - no marker, no default → raise (caught earlier by
+        `validate_target_signature` for well-formed targets).
+    """
+    sig = inspect.signature(fn)
+    hints = _safe_get_type_hints(fn)
+    kwargs: dict[str, Any] = {}
+    for param in sig.parameters.values():
+        kind_err = _param_kind_error(param)
+        if kind_err is not None:
+            raise TypeError(kind_err)
+        annotation = hints.get(param.name)
+        marker = _marker_for(annotation)
+        if marker is _TARGET_MARKER:
+            if param.name not in _TARGETS_BY_NAME:
+                msg = (
+                    f"hm: target {param.name!r} not found\n"
+                    "  → declare it with @hm.target() or rename the "
+                    "parameter to match an existing target"
+                )
+                raise TypeError(msg)
+            kwargs[param.name] = _TARGETS_BY_NAME[param.name]()
+            continue
+        if isinstance(marker, _BaseImageMarker):
+            kwargs[param.name] = Step(image=marker.image)
+            continue
+        if param.default is not inspect.Parameter.empty:
+            kwargs[param.name] = param.default
+            continue
+        msg = (
+            f"hm: parameter {param.name!r} has no marker and no default\n"
+            '  → annotate with Target[T] or BaseImage["..."], or '
+            "give it a default"
+        )
+        raise TypeError(msg)
+    return kwargs
+
+
+def call_with_deps(fn: Callable[..., Any]) -> Any:
+    """Resolve ``fn``'s parameters and call it. Detects cycles."""
+    name = fn.__name__
+    if name in _RESOLVING:
+        cycle = " → ".join([*_RESOLVING, name])
+        msg = (
+            f"hm: dependency cycle detected\n"
+            f"  → {cycle}\n"
+            "  fix: break the cycle, or extract a shared root target"
+        )
+        raise RuntimeError(msg)
+    _RESOLVING.append(name)
+    try:
+        return fn(**resolve_deps(fn))
+    finally:
+        _RESOLVING.pop()

harmont/_envelope.py

@@ -0,0 +1,100 @@
+"""Envelope renderer — produces the schema_version=1 JSON document.
+
+See docs/superpowers/specs/2026-05-10-har-9-imperfect-dsl-design.md
+§ "The envelope" for the wire format.
+
+Each registered pipeline carries its resolved v0 IR as a nested
+``definition`` object. Consumers (api, cli) read that directly — no
+intermediate Scheme stage exists since HAR-16.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ._registry import REGISTRATIONS, PipelineRegistration
+from ._target import clear_target_memo
+from ._unwrap import as_leaves
+from .keygen import resolve_pipeline_keys
+from .pipeline import pipeline as _assemble
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+def _render_one(
+    reg: PipelineRegistration,
+    *,
+    pipeline_org: str,
+    now: int,
+    base_path: Path,
+    env: Mapping[str, str],
+) -> dict[str, Any]:
+    raw = reg.fn()
+    try:
+        leaves = as_leaves(raw)
+    except TypeError as e:
+        msg = (
+            f"pipeline {reg.slug!r}: invalid return value\n"
+            f"  → {e}"
+        )
+        raise TypeError(msg) from e
+    ir = _assemble(*leaves, env=reg.env, default_image=reg.default_image)
+    resolve_pipeline_keys(
+        ir.get("steps", []),
+        pipeline_org=pipeline_org,
+        pipeline_slug=reg.slug,
+        now=now,
+        base_path=base_path,
+        env=env,
+    )
+    return {
+        "slug": reg.slug,
+        "name": reg.name,
+        "allow_manual": reg.allow_manual,
+        "triggers": [t.to_dict() for t in reg.triggers],
+        "definition": ir,
+    }
+
+
+def dump_registry_json(
+    *,
+    pipeline_org: str | None = None,
+    now: int | None = None,
+    base_path: Path | None = None,
+    env: Mapping[str, str] | None = None,
+) -> str:
+    """Emit the schema_version=1 envelope JSON.
+
+    Defaults mirror ``pipeline_to_json``:
+      ``pipeline_org`` <- ``env["HARMONT_PIPELINE_ORG"]`` or ``"default"``
+      ``now``          <- ``int(time.time())``
+      ``base_path``    <- ``Path.cwd()`` (resolves ``on_change`` cache paths)
+      ``env``          <- ``os.environ``
+    Per-pipeline slug is read from each registration.
+
+    The target memoization cache is cleared at the start of each render
+    so per-pipeline target invocations dedup within a single render but
+    don't leak across renders. The named-target registry is left intact
+    so pipeline fixture-style params can resolve their dependencies.
+    """
+    clear_target_memo()
+    env_map: Mapping[str, str] = env if env is not None else os.environ
+    org = pipeline_org if pipeline_org is not None else env_map.get(
+        "HARMONT_PIPELINE_ORG", "default"
+    )
+    render_now = now if now is not None else int(time.time())
+    bp = base_path if base_path is not None else Path.cwd()
+    return json.dumps(
+        {
+            "schema_version": "1",
+            "pipelines": [
+                _render_one(reg, pipeline_org=org, now=render_now, base_path=bp, env=env_map)
+                for reg in REGISTRATIONS
+            ],
+        }
+    )

harmont/_keys.py

@@ -0,0 +1,121 @@
+"""Key derivation for chain-DSL steps.
+
+Order of precedence per the design doc:
+  1. explicit `key=` override on .sh()
+  2. slugified label (when unique within the pipeline)
+  3. stable 12-char hash of (parent_resolved_key, cmd, position)
+
+Collision policy: when two steps' label-slugs collide and neither
+claimed the slug via explicit `key=`, both fall back to hash. An
+explicit override always wins, even if it would collide with another
+step's natural slug.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from ._step import Step
+
+_EMOJI_SHORTCODE_RE = re.compile(r":[a-z0-9_+-]+:")
+_NON_ALNUM_RE = re.compile(r"[^a-z0-9]+")
+
+
+def slugify_label(label: str) -> str:
+    """Lowercase, strip ``:emoji_codes:``, replace non-alnum runs with ``-``,
+    trim leading/trailing dashes.
+
+    Slugs are ASCII-only by policy (matches Buildkite). Non-ASCII
+    letters are treated as separators: ``"Café Build"`` slugs to
+    ``"caf-build"`` and ``"构建"`` slugs to ``""``. Labels that reduce
+    to the empty string fall back to a hash key in ``resolve_keys``;
+    the user's label is preserved on the step's ``label`` field for
+    display, only the cross-reference key is hash-based.
+    """
+    s = label.lower()
+    s = _EMOJI_SHORTCODE_RE.sub(" ", s)
+    s = _NON_ALNUM_RE.sub("-", s)
+    return s.strip("-")
+
+
+def hash_key(parent_key: str, cmd: str, position: int) -> str:
+    """Stable 12-char SHA-256 prefix over (parent_key, cmd, position).
+
+    Used as the fallback key when no usable slug is available."""
+    h = hashlib.sha256()
+    h.update(parent_key.encode("utf-8"))
+    h.update(b"\x00")
+    h.update(cmd.encode("utf-8"))
+    h.update(b"\x00")
+    h.update(str(position).encode("utf-8"))
+    return h.hexdigest()[:12]
+
+
+def resolve_keys(steps: Iterable[Step]) -> dict[int, str]:
+    """Resolve each Step's key. Returns ``{id(step): key}``.
+
+    The ``id()`` indexing is deliberate: two structurally-equal Steps
+    that arose from independent fork branches must keep distinct keys,
+    and frozen-dataclass equality would conflate them.
+    """
+    steps_list = list(steps)
+
+    overrides: dict[int, str] = {}
+    # Natural slug per step (computed for every labeled step, even
+    # those with explicit overrides — see slug_counts below).
+    natural_slugs: dict[int, str] = {}
+    for s in steps_list:
+        if s.key_override is not None:
+            overrides[id(s)] = s.key_override
+        if s.label is not None:
+            slug = slugify_label(s.label)
+            if slug:
+                natural_slugs[id(s)] = slug
+
+    # Reserve every override; any natural slug that matches a reserved
+    # override is a collision for the slug claimant.
+    reserved = set(overrides.values())
+
+    # Detect slug collisions across every labeled step — including those
+    # with explicit overrides. An override-bearing step still "claims"
+    # its natural slug for collision purposes, so a peer with the same
+    # label can't quietly take it.
+    slug_counts: dict[str, int] = {}
+    for slug in natural_slugs.values():
+        slug_counts[slug] = slug_counts.get(slug, 0) + 1
+
+    # The slug pool that non-override steps may draw from: only steps
+    # without a `key=` override are eligible to receive their slug.
+    label_slugs: dict[int, str] = {
+        sid: slug for sid, slug in natural_slugs.items() if sid not in overrides
+    }
+
+    keys: dict[int, str] = {}
+    for position, s in enumerate(steps_list):
+        sid = id(s)
+        if sid in overrides:
+            keys[sid] = overrides[sid]
+            continue
+        candidate_slug = label_slugs.get(sid)
+        if (
+            candidate_slug is not None
+            and candidate_slug not in reserved
+            and slug_counts[candidate_slug] == 1
+        ):
+            keys[sid] = candidate_slug
+            reserved.add(candidate_slug)
+            continue
+        # Fall back to hash. Parent resolved key may not be in `keys`
+        # yet; use the empty string as a sentinel — call sites that
+        # need the resolved parent_key pass it explicitly via the
+        # lowering pass (see pipeline.py).
+        parent_key = ""
+        if s.parent is not None and id(s.parent) in keys:
+            parent_key = keys[id(s.parent)]
+        keys[sid] = hash_key(parent_key, s.cmd or "", position)
+    return keys

harmont/_registry.py

@@ -0,0 +1,44 @@
+"""Module-level registry of @pipeline-decorated functions.
+
+Stage 1 (`dump_registry_json` in `_envelope`) walks REGISTRATIONS to
+emit the envelope JSON the api/cli consume.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from .triggers import Trigger
+
+
+@dataclass(frozen=True)
+class PipelineRegistration:
+    slug: str
+    name: str
+    triggers: tuple[Trigger, ...]
+    allow_manual: bool
+    env: dict[str, str] | None
+    default_image: str | None
+    fn: Callable[[], object]
+
+
+REGISTRATIONS: list[PipelineRegistration] = []
+
+
+def register(reg: PipelineRegistration) -> None:
+    """Append a registration; raise on duplicate slug."""
+    if any(r.slug == reg.slug for r in REGISTRATIONS):
+        msg = (
+            f"duplicate pipeline slug {reg.slug!r}\n"
+            f"  → each @hm.pipeline must have a unique slug"
+        )
+        raise ValueError(msg)
+    REGISTRATIONS.append(reg)
+
+
+def clear_registry() -> None:
+    """Wipe REGISTRATIONS. Test-fixture helper; not part of the public surface."""
+    REGISTRATIONS.clear()