specromancy-engine 0.1.3__py3-none-any.whl

specromancy_engine/hashing.py

@@ -0,0 +1,95 @@
+"""Canonical SHA-256 helpers and safe relative-path handling."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+
+SHA256_PATTERN = re.compile(r"^[0-9a-f]{64}$")
+
+
+def canonical_json_bytes(value: Any) -> bytes:
+    """Serialize JSON data in the canonical form used by persisted hashes."""
+
+    return json.dumps(
+        value,
+        ensure_ascii=False,
+        allow_nan=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+
+
+def sha256_bytes(content: bytes) -> str:
+    return hashlib.sha256(content).hexdigest()
+
+
+def sha256_text(content: str) -> str:
+    return sha256_bytes(content.encode("utf-8"))
+
+
+def sha256_json(value: Any) -> str:
+    return sha256_bytes(canonical_json_bytes(value))
+
+
+def sha256_file(path: str | os.PathLike[str]) -> str:
+    """Hash a regular file without normalizing its contents."""
+
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def normalize_relative_path(path: str | os.PathLike[str]) -> str:
+    """Return a normalized POSIX path, rejecting absolute and dot paths."""
+
+    raw = os.fspath(path)
+    if not raw or "\\" in raw or raw.startswith("/") or re.match(r"^[A-Za-z]:", raw):
+        raise ValueError(f"path must be a non-empty relative POSIX path: {raw!r}")
+    pure = PurePosixPath(raw)
+    if any(part in {"", ".", ".."} for part in pure.parts):
+        raise ValueError(f"path contains a dot segment: {raw!r}")
+    normalized = pure.as_posix()
+    if normalized != raw:
+        raise ValueError(f"path is not normalized: {raw!r}")
+    return normalized
+
+
+def relative_path(path: Path, root: Path) -> str:
+    """Return a normalized path relative to an already trusted root."""
+
+    resolved_root = root.resolve()
+    resolved = path.resolve()
+    if not resolved.is_relative_to(resolved_root):
+        raise ValueError(f"path resolves outside root: {path}")
+    return normalize_relative_path(resolved.relative_to(resolved_root).as_posix())
+
+
+def resolve_relative_path(
+    root: str | os.PathLike[str],
+    relative: str | os.PathLike[str],
+    *,
+    must_exist: bool = False,
+) -> Path:
+    """Resolve a normalized relative path and reject symlink escapes."""
+
+    normalized = normalize_relative_path(relative)
+    resolved_root = Path(root).resolve(strict=True)
+    candidate = (resolved_root / normalized).resolve(strict=must_exist)
+    if not candidate.is_relative_to(resolved_root):
+        raise ValueError(f"path resolves outside root: {normalized!r}")
+    return candidate
+
+
+# Concise aliases are useful at call sites and preserve the public terminology.
+hash_bytes = sha256_bytes
+hash_text = sha256_text
+hash_json = sha256_json
+hash_file = sha256_file

specromancy_engine/locking.py

@@ -0,0 +1,107 @@
+"""Per-run lock files implemented with exclusive standard-library creation."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Callable
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .errors import SpecromancyError
+from .exit_codes import ExitCode
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _timestamp(value: datetime) -> str:
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+class LockHeldError(SpecromancyError):
+    """Raised when another process owns a run's lock file."""
+
+    def __init__(self, path: Path, owner: dict[str, Any] | None = None) -> None:
+        details: dict[str, Any] = {
+            "lock_path": str(path),
+            "remediation": (
+                "verify that the recorded process is no longer running, then remove "
+                "the lock file manually"
+            ),
+        }
+        if owner is not None:
+            details["owner"] = owner
+        super().__init__(ExitCode.LOCK_HELD, f"run lock is already held: {path}", details)
+
+
+class RunLock:
+    """An exclusive lock that records PID and acquisition time for diagnosis."""
+
+    def __init__(
+        self,
+        path: str | os.PathLike[str],
+        *,
+        clock: Callable[[], datetime] = _utc_now,
+    ) -> None:
+        self.path = Path(path)
+        self._clock = clock
+        self._fd: int | None = None
+
+    def acquire(self) -> "RunLock":
+        if self._fd is not None:
+            raise RuntimeError("lock is already acquired by this object")
+        payload = {
+            "pid": os.getpid(),
+            "acquired_at": _timestamp(self._clock()),
+        }
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+        try:
+            descriptor = os.open(self.path, flags, 0o600)
+        except FileExistsError as exc:
+            raise LockHeldError(self.path, _read_owner(self.path)) from exc
+        try:
+            content = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+            os.write(descriptor, (content + "\n").encode("utf-8"))
+            os.fsync(descriptor)
+        except BaseException:
+            os.close(descriptor)
+            self.path.unlink(missing_ok=True)
+            raise
+        self._fd = descriptor
+        return self
+
+    def release(self) -> None:
+        if self._fd is None:
+            return
+        descriptor = self._fd
+        self._fd = None
+        os.close(descriptor)
+        try:
+            self.path.unlink()
+        except FileNotFoundError:
+            # Losing an owned lock is unsafe: another writer could already be active.
+            raise RuntimeError(f"owned lock disappeared before release: {self.path}")
+
+    def __enter__(self) -> "RunLock":
+        return self.acquire()
+
+    def __exit__(self, exc_type: Any, exc: Any, traceback: Any) -> None:
+        self.release()
+
+
+def _read_owner(path: Path) -> dict[str, Any] | None:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return None
+    if not isinstance(value, dict):
+        return None
+    return value
+
+
+FileLock = RunLock

specromancy_engine/registry.py

@@ -0,0 +1,134 @@
+"""Repository-owned registrations for independently configured pipelines."""
+
+from __future__ import annotations
+
+import json
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import NoReturn
+
+from ._config.config_errors import PipelineConfigError
+from ._config.config_loader import IDENTIFIER_PATTERN, load_pipeline
+from ._config.config_models import PipelineConfig
+
+
+REGISTRY_PATH = "workflow/pipelines.toml"
+PIPELINE_PATH_PATTERN = re.compile(r"^pipelines/(?:[A-Za-z0-9_-]+/)*[A-Za-z0-9_-]+\.toml$")
+
+
+@dataclass(frozen=True, slots=True)
+class PipelineRegistration:
+    id: str
+    path: Path
+
+
+@dataclass(frozen=True, slots=True)
+class PipelineRegistry:
+    path: Path
+    repository_root: Path
+    pipelines: tuple[PipelineRegistration, ...]
+
+    @property
+    def canonical_json(self) -> str:
+        return json.dumps(
+            {
+                "schema_version": 1,
+                "pipelines": [
+                    {"id": item.id, "path": item.path.relative_to(self.path.parent).as_posix()}
+                    for item in self.pipelines
+                ],
+            },
+            sort_keys=True,
+            separators=(",", ":"),
+        )
+
+    def load(self, pipeline_id: str) -> PipelineConfig:
+        for registration in self.pipelines:
+            if registration.id == pipeline_id:
+                pipeline = load_pipeline(registration.path, self.repository_root)
+                if pipeline.id != registration.id:
+                    raise PipelineConfigError(
+                        "pipeline-id-mismatch",
+                        "registered ID differs from pipeline ID",
+                        path=self.path,
+                        field="pipelines.id",
+                        value=pipeline_id,
+                        remediation="make the registration and pipeline IDs agree",
+                    )
+                return pipeline
+        raise PipelineConfigError(
+            "unknown-pipeline",
+            f"pipeline {pipeline_id!r} is not registered",
+            path=self.path,
+            field="pipelines.id",
+            value=pipeline_id,
+            remediation="choose a registered ID: " + ", ".join(item.id for item in self.pipelines),
+        )
+
+    def load_all(self) -> tuple[PipelineConfig, ...]:
+        return tuple(self.load(item.id) for item in self.pipelines)
+
+
+def load_registry(repository_root: str | Path) -> PipelineRegistry:
+    """Validate the mandatory registry without loading unrelated phase graphs."""
+
+    root = Path(repository_root).expanduser().resolve()
+    path = root / REGISTRY_PATH
+
+    def fail(code: str, message: str, field: str, value: object = None) -> NoReturn:
+        raise PipelineConfigError(
+            code,
+            message,
+            path=path,
+            field=field,
+            value=value,
+            remediation="use schema_version = 1 and unique [[pipelines]] id/path entries under workflow/pipelines/",
+        )
+
+    try:
+        if not path.resolve().is_relative_to(root):
+            fail("unsafe-registry-path", "registry resolves outside the repository", "registry")
+        with path.open("rb") as stream:
+            raw = tomllib.load(stream)
+    except (OSError, ValueError, RuntimeError) as exc:
+        fail("invalid-registry", f"cannot load mandatory registry: {exc}", "registry")
+    if set(raw) != {"schema_version", "pipelines"}:
+        fail("invalid-registry-fields", "registry requires only schema_version and pipelines", "registry")
+    if type(raw["schema_version"]) is not int or raw["schema_version"] != 1:
+        fail("unsupported-schema-version", "registry schema_version must be 1", "schema_version", raw["schema_version"])
+    entries = raw["pipelines"]
+    if not isinstance(entries, list) or not entries:
+        fail("empty-registry", "pipelines must be a nonempty array of tables", "pipelines")
+    registrations: list[PipelineRegistration] = []
+    ids: set[str] = set()
+    paths: set[Path] = set()
+    directory = root / "workflow" / "pipelines"
+    for entry in entries:
+        if not isinstance(entry, dict) or set(entry) != {"id", "path"}:
+            fail("invalid-registration", "registration requires only id and path", "pipelines", entry)
+        pipeline_id = entry["id"]
+        if not isinstance(pipeline_id, str) or not IDENTIFIER_PATTERN.fullmatch(pipeline_id):
+            fail("invalid-identifier", "pipeline ID must be lowercase kebab-case", "pipelines.id", pipeline_id)
+        if pipeline_id in ids:
+            fail("duplicate-pipeline-id", "pipeline IDs must be unique", "pipelines.id", pipeline_id)
+        declared = entry["path"]
+        if not isinstance(declared, str):
+            fail("unsafe-pipeline-path", "pipeline path must be a relative TOML path", "pipelines.path", declared)
+        if not PIPELINE_PATH_PATTERN.fullmatch(declared):
+            fail("unsafe-pipeline-path", "pipeline path must be under pipelines/", "pipelines.path", declared)
+        try:
+            resolved = (path.parent / declared).resolve()
+        except (OSError, ValueError, RuntimeError) as exc:
+            fail("unsafe-pipeline-path", f"pipeline path cannot be resolved: {exc}", "pipelines.path", declared)
+        if not resolved.is_relative_to(directory) or not resolved.is_relative_to(root):
+            fail("unsafe-pipeline-path", "pipeline path escapes workflow/pipelines/", "pipelines.path", declared)
+        if not resolved.is_file():
+            fail("missing-pipeline", "registered pipeline file does not exist", "pipelines.path", declared)
+        if resolved in paths:
+            fail("duplicate-pipeline-path", "pipeline paths must be unique", "pipelines.path", declared)
+        ids.add(pipeline_id)
+        paths.add(resolved)
+        registrations.append(PipelineRegistration(pipeline_id, resolved))
+    return PipelineRegistry(path, root, tuple(sorted(registrations, key=lambda item: item.id)))