syncade 0.6.2__py3-none-any.whl

syncade/config_loader.py

@@ -0,0 +1,182 @@
+"""Load and validate ``.syncade/config.toml``.
+
+The loader is intentionally tolerant of a missing config file (returns PRD
+defaults silently) but strict about invalid content: TOML parse errors and
+pydantic validation failures are both wrapped in :class:`ConfigError` with
+a message that names the offending field(s) when possible.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from syncade.config import SyncadeConfig
+from syncade.config_auth import api_key_problems
+from syncade.presets import load_preset
+
+CONFIG_RELATIVE_PATH: Path = Path(".syncade") / "config.toml"
+"""Path of the config file relative to a repo root."""
+
+
+class ConfigError(Exception):
+    """Raised when ``.syncade/config.toml`` cannot be parsed or fails schema
+    validation.
+
+    The exception message names the offending field(s) when possible so the
+    CLI can surface a self-explanatory error to the user without further
+    introspection of the underlying cause.
+    """
+
+
+# Top-level tables whose provider/model form a PAIR (config.py re-derives model from provider). A
+# higher layer that names one of these replaces it WHOLESALE, so the pair can never split across
+# layers (global sets anthropic/claude, repo overrides provider=openai -> a consistent openai pair,
+# never openai + a claude model). Everything else merges key-by-key; lists/scalars replace.
+_PAIRED_SECTIONS = frozenset({"producer", "synthesizer", "drafter", "auditor"})
+
+
+def _deep_merge(base: dict, override: dict, *, _top_level: bool = True) -> dict:
+    """Merge ``override`` onto ``base`` (override wins). Tables merge key-by-key EXCEPT the
+    TOP-LEVEL paired sections (:data:`_PAIRED_SECTIONS`), which replace wholesale; lists and scalars
+    replace. Layers the chain: defaults < ``--preset`` < global (``~/.syncade``) < repo
+    (``.syncade``). The paired-section rule is TOP-LEVEL ONLY (D2): ``_top_level=False`` on recurse
+    so a nested table that merely SHARES a paired name (e.g. a ``[pricing.models.producer]`` for a
+    model named ``producer``) still key-merges instead of being wholesale-replaced."""
+    out = dict(base)
+    for key, value in override.items():
+        if _top_level and key in _PAIRED_SECTIONS:
+            out[key] = value
+        elif isinstance(value, dict) and isinstance(out.get(key), dict):
+            out[key] = _deep_merge(out[key], value, _top_level=False)
+        else:
+            out[key] = value
+    return out
+
+
+def _default_global_config_path() -> Path:
+    """``~/.syncade/config.toml`` — the global config layer. A function (not a constant) so tests
+    can monkeypatch it to an isolated path without touching ``$HOME``."""
+    return Path.home() / ".syncade" / "config.toml"
+
+
+def _read_toml(path: Path) -> dict:
+    """Parse ``path`` to a dict; ``{}`` if it is absent. Read/parse failures raise
+    :class:`ConfigError` naming ``path``, so a bad global vs repo file is unambiguous."""
+    try:
+        if not path.is_file():
+            return {}
+    except OSError as exc:
+        raise ConfigError(f"Failed to inspect {path}: {exc}") from exc
+    try:
+        with path.open("rb") as f:
+            return tomllib.load(f)
+    except OSError as exc:
+        raise ConfigError(f"Failed to read {path}: {exc}") from exc
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"Failed to parse {path}: {exc}") from exc
+
+
+def load_config(
+    repo_root: Path,
+    *,
+    preset: str | None = None,
+    check_api_keys: bool = True,
+    deprecation_callback=None,
+    env: dict[str, str] | None = None,
+    global_config_path: Path | None = None,
+    include_repo: bool = True,
+) -> SyncadeConfig:
+    """Load and validate ``<repo_root>/.syncade/config.toml``.
+
+    Behaviour:
+
+    - If the file is missing, returns :class:`SyncadeConfig` with all PRD
+      defaults applied (or the ``preset`` base, if given). No warning is
+      emitted — zero-config is a supported and expected mode.
+    - Precedence is defaults < ``preset`` < ``~/.syncade/config.toml`` (global) <
+      the repo's ``.syncade/config.toml`` < CLI flags. Each layer deep-merges onto
+      the one below (higher wins), except the paired sections replace wholesale
+      (see :func:`_deep_merge`). A missing layer is skipped; with no global and no
+      repo file, the result is byte-identical to zero-config today.
+    - If the file exists but is syntactically invalid TOML, raises
+      :class:`ConfigError` referencing the parse error.
+    - If the file parses but fails schema validation (unknown field,
+      invalid enum value, wrong type, etc.), raises :class:`ConfigError`
+      whose message names the offending dotted field path(s).
+
+    Args:
+        repo_root: The git repo root to load config from.
+        preset: Optional bundled preset name; its TOML is the base config the
+            user file deep-merges onto (see :func:`syncade.presets.load_preset`).
+        check_api_keys: When ``True`` (default), an ``auth = "api"`` actor with no
+            key in the env fails as a config error. Set ``False`` for actor-less
+            maintenance modes (``--gc``) that must not require credentials for
+            actors they never spawn — malformed TOML / bad schema still fail.
+        deprecation_callback: Retained for the CLI call shape. There are no
+            current load-time deprecations; stale fields now fail validation.
+        env: Environment consulted for the ANTHROPIC ``auth = "api"`` key check (openai
+            is exempt -- codex reads no env key). Defaults to ``os.environ``. An explicit
+            parameter rather than a global read, so tests can exercise the check without
+            mutating process state — and so the env-dependence of config loading is
+            visible in the signature.
+        global_config_path: The global layer (defaults to ``~/.syncade/config.toml``). Tests pass
+            an explicit path to exercise or isolate it; production uses the default.
+        include_repo: When ``True`` (default), the repo layer (``<repo_root>/.syncade/config.toml``)
+            participates. ``False`` drops it — used by ``--config`` when the cwd is NOT inside a git
+            repo. ``--config`` inspects the CURRENT state (no repo → no repo layer), so a stray
+            ``cwd/.syncade/config.toml`` is not read as the repo layer. (A *review* run with
+            ``--allow-auto-init`` would ``git init`` the dir first and THEN read that file; without
+            it, a non-empty dir is refused. ``--config`` surfaces the divergence as a note rather
+            than silently adopting or ignoring the file.)
+    """
+    global_path = (
+        global_config_path if global_config_path is not None else _default_global_config_path()
+    )
+    repo_path = repo_root / CONFIG_RELATIVE_PATH
+
+    # defaults(< preset) < global < repo. A missing layer contributes {} and is not blamed on error.
+    raw = load_preset(preset) if preset else {}
+    sources: list[Path] = []
+    layer_paths = (global_path, repo_path) if include_repo else (global_path,)
+    for path in layer_paths:
+        layer = _read_toml(path)
+        if layer:
+            raw = _deep_merge(raw, layer)
+            sources.append(path)
+    where = " + ".join(str(p) for p in sources) or "configuration"
+
+    try:
+        config = SyncadeConfig.model_validate(raw)
+    except ValidationError as exc:
+        raise ConfigError(
+            f"Invalid configuration in {where}:\n{_format_validation_errors(exc)}"
+        ) from exc
+
+    # auth = "api" with no key in the env is a CONFIG error, not a runtime one. Left to
+    # runtime it surfaces as a provider 401 — after every reviewer has already run and
+    # billed. Every offending actor is reported at once so one re-run fixes them all.
+    # ``check_api_keys=False`` for actor-less maintenance modes (e.g. ``--gc``): they still
+    # reject malformed TOML / bad schema above, but must not require credentials for actors
+    # they will never spawn (dogfood R2-B2).
+    if check_api_keys:
+        problems = api_key_problems(config, env=env)
+        if problems:
+            raise ConfigError(
+                "Invalid configuration in {}:\n{}".format(
+                    where, "\n".join(f"  - {p}" for p in problems)
+                )
+            )
+    return config
+
+
+def _format_validation_errors(exc: ValidationError) -> str:
+    """Render a :class:`pydantic.ValidationError` as a human-readable
+    bulleted list of ``<dotted.field>: <message>`` lines."""
+    lines: list[str] = []
+    for err in exc.errors():
+        loc = ".".join(str(part) for part in err["loc"]) or "<root>"
+        lines.append(f"  - {loc}: {err['msg']}")
+    return "\n".join(lines)

syncade/config_loop.py

@@ -0,0 +1,282 @@
+"""[loop] convergence-loop config.
+
+:class:`LoopConfig` for the ``[loop]`` block. Imports only stdlib + pydantic
+(no dependency on ``config`` itself), so it extracts without a circular import.
+Re-exported from ``config`` so the ``syncade.config.LoopConfig`` import path is
+unchanged.
+"""
+
+from __future__ import annotations
+
+import math
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class LoopConfig(BaseModel):
+    """Convergence-loop tuning."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    max_rounds: int = Field(
+        default=5,
+        ge=1,
+        le=10,
+        description=(
+            "Per-run maximum rounds of (reviewers → synthesizer → "
+            "optional test → producer-if-NO-SHIP). The loop terminates "
+            "as soon as SHIP fires (exit 0, termination_reason='ship') "
+            "at any round, or the diff is known-empty before dispatch "
+            "(exit 0, termination_reason='no_changes_to_review') — "
+            "``max_rounds`` is the ceiling, not a target. Bounded to "
+            "[1, 10] (PR-v2-31, raised from 3); values outside that range "
+            "are rejected at config load. 10 is a typo-ceiling, not the "
+            "safety mechanism — budget_tokens/budget_usd (PR-v2-11) and the "
+            "per-subprocess timeout are the real runaway guards. Set to 1 for "
+            "single-pass operation with no producer subprocess."
+        ),
+    )
+    timeout_seconds: float = Field(
+        # 1800.0, not 1800: the annotation says float, and an int default makes pydantic 2.0
+        # emit a serializer warning on every `config.model_dump()` ("Expected `float` but got
+        # `int`"). Harmless in isolation, fatal in context — the loop's own test leg runs
+        # `pytest -W error`, so at the declared floor that one int turned 279 tests red while
+        # the dev machine (pydantic 2.13) saw nothing (PR-h-10 item 4).
+        default=1800.0,
+        gt=0,
+        description="Per-subprocess wall-clock timeout in seconds. The fallback "
+        "wall-clock cap for every leg: each reviewer, the judge, the test run, "
+        "each mechanical check, and the producer. Default 1800 (30 minutes) — "
+        "sized for a thorough real review. Must be > 0 and finite (NaN and "
+        "infinity rejected via a field_validator; pydantic's gt=0 admits both "
+        "unaided). The CLI's --timeout flag overrides this per-invocation.",
+    )
+    max_diff_bytes: int = Field(
+        default=1_000_000,
+        gt=0,
+        description=(
+            "Ceiling on the REVIEWER-FACING diff, in UTF-8 bytes — measured after "
+            "repo-context stripping and binary elision, i.e. exactly what reaches the "
+            "model's context, not what the repo produced. A run whose diff exceeds it is "
+            "refused before any subprocess is dispatched (exit 60, "
+            "termination_reason='diff_too_large'), consistent with diff_malformed: if we "
+            "cannot show reviewers the change, we decline to render a verdict on it. "
+            "Narrow --base or split the PR.\n\n"
+            "The default is calibrated, not guessed, in two directions. Upper bound: "
+            "`codex exec` hard-refuses input over 1,048,576 CHARACTERS "
+            "(input_error_code=input_too_large) — a UTF-8 byte cap of 1,000,000 keeps the "
+            "diff under that in every encoding, since bytes >= characters, so syncade's own "
+            "actionable message always fires before the provider's opaque one. Lower bound: "
+            "across the 30 measured rounds in this repo's run corpus the largest "
+            "reviewer-facing diff was 147,171 B (median 77,026), so the default has ~7x "
+            "headroom over observed reality and refuses nothing that works today. Lower it "
+            "deliberately if you want a tighter review surface — this wave's evidence is "
+            "that large diffs converge poorly (a 25-commit diff gave 4/4/4/3/5 findings and "
+            "never converged; a 3-commit one gave 1/1/0 to SHIP on the same panel).\n\n"
+            "NOT a token cap: `claude -p` limits by TOKENS (1,000,000), which bytes cannot "
+            "predict, so a token-limit refusal is still possible on that provider."
+        ),
+    )
+    budget_tokens: int | None = Field(
+        default=50_000_000,
+        ge=0,
+        description=(
+            "Optional per-RUN total-token ceiling (PR-v2-11). When the running tally of every "
+            "actor's usage crosses it at a phase boundary, the loop aborts gracefully with "
+            "termination_reason='budget_exceeded'. total_tokens is recorded for every actor "
+            "whose provider returned usage (the norm — captured even when the reviewer's OUTPUT "
+            "fails to parse), so this is the TIGHTEST cap available: exact when all actors "
+            "report usage, and a lower bound only if an actor reports none (a provider envelope "
+            "with no usage block). Always at least as tight as budget_usd, which ALSO drops "
+            "actors whose COST could not be priced. 0 = no token ceiling (opt-out sentinel; "
+            "TOML has no null, so 0 is the only way to express 'unlimited' once a default "
+            "exists). The CLI's --budget-tokens flag overrides this per-invocation. An int, "
+            "so NaN/inf cannot arise and ge=0 already rejects negatives.\n\n"
+            "DEFAULT 50,000,000 (PR-h-field-06). Previously unset, which left a first run "
+            "bounded only by max_rounds x the per-subprocess timeout — and the round default "
+            "moved 3 -> 5 in v0.6.1, widening that ~66%. Chosen against this repo's corpus "
+            "rather than picked round: across 102 priced runs the median run spent 11.0M "
+            "tokens and p90 spent 38.8M, so 50M would have stopped 4 of 102 (4%). Tokens "
+            "rather than dollars because cost_usd is an API-EQUIVALENT VALUATION and most "
+            "traffic is subscription, where a dollar ceiling would interrupt a run over money "
+            "nobody spent.\n\n"
+            "SET TO 0 FOR NO CEILING. TOML has no null, so once a default exists an omitted "
+            "key can no longer mean 'unlimited' — 0 is the opt-out. It reads as a ceiling of "
+            "zero only if you ignore that a zero ceiling would stop every run before it "
+            "started, which is why it is free to mean the opposite."
+        ),
+    )
+    budget_usd: float | None = Field(
+        default=None,
+        ge=0,
+        description=(
+            "Optional per-RUN cost ceiling (PR-v2-11) on the API-EQUIVALENT VALUATION "
+            "(PR-v2-24), NOT billed money — on a subscription the marginal dollar is $0, so "
+            "this bounds the WORK, matching what `syncade --doctor` previews and `--metrics` "
+            "reports. A LOWER-BOUND tally: actors with incomplete cost contribute uncounted, "
+            "so a dollar-budgeted run can overshoot silently (use budget_tokens for a hard "
+            "cap). None (default) = no cost ceiling. Must be >= 0 and finite (NaN/inf rejected "
+            "via a field_validator; pydantic's gt=0 admits both). The CLI's --budget-usd flag "
+            "overrides this per-invocation.\n\n"
+            "SET TO 0 FOR NO CEILING, symmetric with budget_tokens. Added in PR-h-field-06 "
+            "after a blind reviewer caught the asymmetry: the stop message offered a dollar "
+            "opt-out that did not exist, and 'remove the key' does not work because --resume "
+            "RE-INHERITS a ceiling the current config omits. An explicit 0 is in "
+            "model_fields_set, so resume treats it as a decision rather than an absence."
+        ),
+    )
+    test_command: str | None = Field(
+        default=None,
+        min_length=1,
+        description=(
+            "Shell command to run as the third convergence leg, "
+            "after all reviewers succeed and the synthesizer produces a "
+            "clean consolidated finding set. Runs in a fresh worktree "
+            "(same blindness mechanism as reviewers: WorktreeManager + "
+            "CLAUDE.md/AGENTS.md stripped). Non-zero exit → exit 30 "
+            "(treated as a blocker); subprocess failure (binary missing, "
+            "timeout) → exit 40. Unset (default) skips the test leg "
+            "entirely — exit 0 reflects synth-clean "
+            "(termination_reason='ship') only; a no_changes_to_review "
+            "early exit takes exit 0 regardless of this setting. The string "
+            "is passed verbatim to ``sh -c`` so operators can use pipes, "
+            "env exports, and multi-command sequences "
+            '(``"npm test && playwright test"``). shell=True is '
+            "intentional: the command comes from the operator's own "
+            "config file, not from untrusted input — same threat model "
+            'as a Makefile or package.json "scripts" entry. '
+            "Whitespace-only strings are rejected at config-load via "
+            "``Field(min_length=1)`` plus a ``field_validator`` so a "
+            'misconfigured ``test_command = "   "`` surfaces as a '
+            "ValidationError rather than silently SIGKILLing every run."
+        ),
+    )
+    test_timeout_seconds: float | None = Field(
+        default=None,
+        gt=0,
+        description=(
+            "Per-test-run wall-clock timeout in seconds. "
+            "``None`` (default) reuses :attr:`timeout_seconds`, which is "
+            "also the reviewer timeout. Set explicitly when the test "
+            "suite has a different expected runtime profile than the "
+            "reviewers (e.g. fast unit suite at 300s vs reviewers at "
+            "1800s). Must be > 0 when set; NaN and infinity are "
+            "rejected via a ``field_validator`` so the same "
+            "``math.isfinite`` guard pattern from the reviewer "
+            "``timeout_seconds`` applies here. The "
+            "``test_timeout_seconds = None`` → reuse-``timeout_seconds`` "
+            "resolution happens in the orchestrator, not in pydantic — "
+            "keeping the field nullable means 'use the default' is "
+            "distinguishable from 'explicitly set to the same value as "
+            "timeout_seconds.'"
+        ),
+    )
+
+    @field_validator("budget_tokens", mode="before")
+    @classmethod
+    def _strict_budget_tokens(cls, value: object) -> object:
+        # Same rule as max_diff_bytes: pydantic's lax mode silently coerces false->0 (the
+        # opt-out sentinel), true->1, 0.0->0, and "0"->0. A TOML typo of
+        # `budget_tokens = false` would silently disable the default safety ceiling rather
+        # than producing a config error — the opposite of a safe failure. Reject all
+        # wrong-type forms (exit 50). None is allowed (the no-default case).
+        if value is not None and (isinstance(value, bool) or not isinstance(value, int)):
+            raise ValueError(
+                f"budget_tokens must be a plain integer or omitted (got {value!r}); "
+                "quoted numbers, floats, and booleans are rejected"
+            )
+        return value
+
+    @field_validator("max_diff_bytes", mode="before")
+    @classmethod
+    def _strict_max_diff_bytes(cls, value: object) -> object:
+        # Same rule as [gc]'s integers (PR-v2-9): pydantic's lax mode silently coerces a
+        # quoted number ("0"->0), an exact float (1.0->1), and a boolean (bool subclasses
+        # int, so true->1). Any of those here is a typo with a severe outcome — true->1
+        # would refuse EVERY run for a one-byte ceiling. Reject all three (exit 50).
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise ValueError(
+                f"max_diff_bytes must be a plain integer (got {value!r}); quoted numbers, "
+                "floats, and booleans are rejected"
+            )
+        return value
+
+    @field_validator("test_command")
+    @classmethod
+    def _test_command_not_whitespace(cls, value: str | None) -> str | None:
+        """Reject ``"   "`` / ``"\\n\\t"`` etc. — schema-only ``min_length``
+        passes them through (length is non-zero) but they'd silently
+        SIGKILL every run when passed to ``sh -c``.
+
+        Mirrors the required-string validation pattern used elsewhere. Keeping
+        ``None`` as the disabled sentinel — only NON-None values are checked for
+        whitespace
+        emptiness.
+        """
+        if value is not None and not value.strip():
+            raise ValueError(
+                "test_command must not be empty or whitespace-only "
+                "(use ``test_command = `` <unset> to disable the test "
+                "leg; the empty / whitespace string is rejected so a "
+                "config typo can't silently disable the leg)"
+            )
+        return value
+
+    @field_validator("budget_usd", mode="before")
+    @classmethod
+    def _strict_budget_usd(cls, value: object) -> object:
+        # Same rule as budget_tokens: pydantic's lax mode coerces false->0.0 (the opt-out
+        # sentinel), true->1.0, and "1.5"->1.5. Because explicit 0 is now the no-ceiling
+        # sentinel and lands in model_fields_set, `budget_usd = false` in a hand-edited repo
+        # config can silently disable an inherited dollar ceiling rather than surfacing a config
+        # error. Reject booleans and non-numeric strings; allow plain int/float and None.
+        if value is not None and (isinstance(value, bool) or not isinstance(value, (int, float))):
+            raise ValueError(
+                f"budget_usd must be a plain numeric value >= 0 or omitted (got {value!r}); "
+                "quoted numbers and booleans are rejected"
+            )
+        return value
+
+    @field_validator("budget_usd")
+    @classmethod
+    def _budget_usd_isfinite(cls, value: float | None) -> float | None:
+        """Same ``math.isfinite`` guard as the timeouts: pydantic's ``gt=0`` admits NaN/inf,
+        and an infinite budget would silently mean 'no ceiling' (it never trips) rather than
+        erroring — hiding a config typo. ``budget_tokens`` needs no twin: it is an int."""
+        if value is not None and not math.isfinite(value):
+            raise ValueError(
+                f"budget_usd must be a finite non-negative number (0 = no ceiling); got {value!r}"
+            )
+        return value
+
+    @field_validator("test_timeout_seconds")
+    @classmethod
+    def _test_timeout_seconds_isfinite(cls, value: float | None) -> float | None:
+        """Reject ``float('nan')`` and ``float('inf')`` — pydantic's
+        ``gt=0`` admits both (inf > 0 is True; nan comparisons are
+        defined to return False so the gt check actually passes
+        with a warning shape in some pydantic versions). The same
+        ``math.isfinite`` guard also applies to the reviewer
+        timeout applies here so a runaway operator config can't
+        produce an unkillable test-run subprocess."""
+        if value is not None and not math.isfinite(value):
+            raise ValueError(
+                f"test_timeout_seconds must be a finite positive number; got {value!r}"
+            )
+        return value
+
+    @field_validator("timeout_seconds")
+    @classmethod
+    def _timeout_seconds_isfinite(cls, value: float) -> float:
+        """Apply the same ``math.isfinite`` guard for reviewer timeouts.
+
+        pydantic's ``gt=0`` admits NaN/inf unaided, which would produce an
+        unkillable reviewer subprocess: the reviewer phase would block forever
+        waiting on the dispatcher's ``communicate(timeout=...)`` since
+        ``timeout=inf`` reads as "wait forever" and ``timeout=nan`` produces
+        undefined comparator behavior. Same field-validator pattern as
+        :meth:`_test_timeout_seconds_isfinite`.
+        """
+        if not math.isfinite(value):
+            raise ValueError(f"timeout_seconds must be a finite positive number; got {value!r}")
+        return value