iCode-TUI 0.29.1__py3-none-any.whl

chrys/foundation/config/coercion.py

@@ -0,0 +1,374 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Value coercion for settings, shared by every configuration layer.
+
+One coercer per field, owned by the field's ``SettingSpec`` — so parsing,
+clamping and fallback live in exactly one place instead of being re-derived by
+each reader (dataclass default, ACP validator, headless warning path, …).
+
+Coercers take a **raw** value from any layer and normalise it to one canonical
+value. YAML hands over already-typed values (``true``, ``50``); dotenv and the
+process environment hand over strings. Both must land on the same result, so
+the grammar below is defined once and every coercer accepts the native type
+and the string spelling of it.
+
+A coercer never raises and never invents a fallback: it reports what the raw
+value *is*.
+
+* ``MISSING`` — this layer says nothing about the field; the loader moves to
+  the next layer down. Absent keys, blank strings and YAML ``null`` all land
+  here.
+* ``VALID`` / ``CLAMPED`` — a usable canonical value, the latter adjusted to a
+  declared bound.
+* ``INVALID`` — unusable. The layer contributes nothing, exactly as if it were
+  ``MISSING``, but a record is produced. What to do with that record is the
+  loader's call: user-visible for a project file (which must be able to say
+  "this key of this file was rejected"), a log line for the historical env
+  behaviour.
+
+Encoding "invalid" as *the field default* — the shape this module had first —
+makes the project layer undecidable: the loader cannot tell a repository that
+legitimately set the default value from one whose garbage was silently
+swallowed, and would label the default as coming from the project.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import Any
+
+TRUTHY = frozenset({"1", "true", "yes", "on"})
+FALSY = frozenset({"0", "false", "no", "off"})
+"""The complete boolean grammar. Any other spelling is invalid, not false."""
+
+
+class CoerceStatus(Enum):
+    """Outcome of coercing one raw value."""
+
+    MISSING = auto()
+    VALID = auto()
+    CLAMPED = auto()
+    INVALID = auto()
+
+
+class CoerceReason(Enum):
+    """Why a value was refused or adjusted, in no particular language.
+
+    An English sentence here would be the one part of a settings warning that
+    cannot be translated: the warning shell is a catalog entry, but a free-text
+    detail composed down in ``foundation`` would arrive already written and
+    render as "Ignoring CHRYS_SESSION_TITLE_AUTO=nonsense" followed by the
+    English "expected a boolean" in the middle of a Chinese sentence.
+    A member is picked instead, and the composer that owns the user-facing copy
+    binds it to a message with the rest of the sentence.
+    """
+
+    EXPECTED_BOOL = auto()
+    EXPECTED_INT = auto()
+    EXPECTED_NON_NEGATIVE_INT = auto()
+    EXPECTED_NUMBER = auto()
+    EXPECTED_FINITE_NUMBER = auto()
+    EXPECTED_TEXT = auto()
+    NOT_A_CHOICE = auto()
+    EXPECTED_JSON_ARRAY = auto()
+    EXPECTED_WEB_ORIGIN = auto()
+    """An address that is not a bare http(s) origin: it has a path, credentials or no scheme."""
+
+    EXPECTED_ENDPOINT_GRANT = auto()
+    BELOW_MINIMUM = auto()
+    ABOVE_MAXIMUM = auto()
+    NOT_A_DIRECTORY = auto()
+    """Reserved for the operational checks a pure coercer cannot make."""
+
+    NOT_ALLOWED_IN_PROJECT = auto()
+    """The key is outside the project-merge whitelist (or not a key at all).
+
+    Not produced by a coercer: the project trust domain rejects the key before
+    any value question is asked, and rides the verdict type so the one warning
+    pipeline carries it.
+    """
+
+    LOOSENS_USER_BASELINE = auto()
+    """A whitelisted key's value moves in the direction the policy forbids.
+
+    Also policy, not grammar: the value coerced fine, but ``TIGHTEN_ONLY`` /
+    ``ENABLE_ONLY`` / ``DISABLE_ONLY`` compare it against the user's own
+    ``DEFAULT + USER`` baseline, and it landed on the loosening side.
+    """
+
+
+@dataclass(frozen=True, slots=True)
+class Coerced:
+    """A coercion outcome.
+
+    ``value`` is meaningful only for ``VALID`` and ``CLAMPED``. ``raw`` is the
+    offending value as written; callers rendering it for a sensitive field must
+    redact it themselves. ``reason``, ``limit`` and ``choices`` carry everything
+    a message needs, so no caller has to parse a sentence back apart.
+    """
+
+    status: CoerceStatus
+    value: Any = None
+    raw: str = ""
+    reason: CoerceReason | None = None
+    limit: float | None = None
+    choices: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        # The composer maps reasons to sentences exhaustively, so a verdict that
+        # arrives without one has no way to be shown to anyone.
+        if self.status in (CoerceStatus.INVALID, CoerceStatus.CLAMPED) and self.reason is None:
+            msg = f"{self.status.name} must name the reason it was rejected or adjusted"
+            raise ValueError(msg)
+
+    @property
+    def usable(self) -> bool:
+        """Whether this layer contributes ``value``."""
+        return self.status in (CoerceStatus.VALID, CoerceStatus.CLAMPED)
+
+
+Coercer = Callable[[object], Coerced]
+
+MISSING = Coerced(status=CoerceStatus.MISSING)
+
+
+def render_raw(raw: object) -> str:
+    """Render *raw* for a warning, without ever raising.
+
+    Public because a field may need its own coercer (a legacy alias whose
+    grammar differs from its key's), and such a coercer reaching for ``str()``
+    or ``repr()`` directly is how the no-raise contract gets broken one field
+    at a time.
+    """
+    if isinstance(raw, str):
+        return raw
+    try:
+        return str(raw)
+    except Exception:
+        # Two different failures, one answer. ``str()`` of an integer past
+        # ``sys.get_int_max_str_digits()`` raises ``ValueError``, and YAML
+        # happily parses one; a raw value that reached us from an unvetted
+        # source can carry any ``__str__`` at all. The declared input type is
+        # ``object``, so narrowing this catch would make the no-raise contract
+        # true only for the values we happened to think of.
+        return f"<unrenderable {type(raw).__name__}>"
+
+
+def invalid(raw: object, reason: CoerceReason, *, choices: tuple[str, ...] = ()) -> Coerced:
+    """Build an ``INVALID`` outcome with a safely rendered ``raw``."""
+    return Coerced(status=CoerceStatus.INVALID, raw=render_raw(raw), reason=reason, choices=choices)
+
+
+def _clamped(raw: object, value: Any, reason: CoerceReason, limit: float) -> Coerced:
+    return Coerced(status=CoerceStatus.CLAMPED, value=value, raw=render_raw(raw), reason=reason, limit=limit)
+
+
+def _valid(value: Any) -> Coerced:
+    return Coerced(status=CoerceStatus.VALID, value=value)
+
+
+def bool_coercer() -> Coercer:
+    """Coerce to bool.
+
+    Accepts native ``bool``, the integers ``0``/``1`` (a common YAML flag
+    spelling), and the string spellings in :data:`TRUTHY` / :data:`FALSY`.
+    Everything else is invalid.
+
+    Note this is stricter than the historical env reader, which treated every
+    non-truthy string as false — so ``CHRYS_SESSION_TITLE_AUTO=nonsense``
+    silently turned the feature off. Garbage now falls through to the layer
+    below instead of meaning "off".
+    """
+
+    def coerce(raw: object) -> Coerced:
+        if raw is None:
+            return MISSING
+        if isinstance(raw, bool):
+            return _valid(raw)
+        if isinstance(raw, str):
+            normalized = raw.strip().lower()
+            if not normalized:
+                return MISSING
+            if normalized in TRUTHY:
+                return _valid(True)
+            if normalized in FALSY:
+                return _valid(False)
+            return invalid(raw, CoerceReason.EXPECTED_BOOL)
+        if isinstance(raw, int) and raw in (0, 1):
+            return _valid(bool(raw))
+        return invalid(raw, CoerceReason.EXPECTED_BOOL)
+
+    return coerce
+
+
+def _to_int(raw: object) -> int | Coerced:
+    """Parse *raw* as an int, or return the failing :class:`Coerced`."""
+    if raw is None:
+        return MISSING
+    if isinstance(raw, bool):
+        # ``bool`` is an ``int`` subclass; accepting it would let ``true`` mean 1.
+        return invalid(raw, CoerceReason.EXPECTED_INT)
+    if isinstance(raw, int):
+        return raw
+    if isinstance(raw, str):
+        normalized = raw.strip()
+        if not normalized:
+            return MISSING
+        try:
+            return int(normalized)
+        except ValueError:
+            return invalid(raw, CoerceReason.EXPECTED_INT)
+    return invalid(raw, CoerceReason.EXPECTED_INT)
+
+
+def int_coercer(
+    *,
+    minimum: int | None = None,
+    maximum: int | None = None,
+    non_positive: int | None = None,
+    zero: int | None = None,
+    reject_negative: bool = False,
+) -> Coercer:
+    """Coerce to int, with the sentinel and bound policy the field declares.
+
+    The knobs exist because "out of range" already means three different things
+    across the existing variables, and flattening them would change behaviour:
+    ``CHRYS_WORKSPACE_MRU_MAX_ENTRIES=-5`` disables the MRU, the same value on
+    ``CHRYS_WORKSPACE_CHANGE_NOTICE_MAX_ENTRIES`` clamps up to 1, and on
+    ``CHRYS_MAX_TRANSIENT_RETRIES`` it is rejected outright.
+
+    Args:
+        minimum: Values below this are raised to it.
+        maximum: Values above this are lowered to it.
+        non_positive: When set, any value ``<= 0`` becomes this, bypassing the
+            bounds — these fields spell "disabled" or "no limit" as ``0`` or as
+            any negative number, so clamping would invert their meaning.
+        zero: When set, exactly ``0`` becomes this, bypassing the bounds.
+        reject_negative: Treat negative values as invalid rather than clamping
+            them. Checked first, so it composes with *zero*.
+    """
+
+    def coerce(raw: object) -> Coerced:
+        parsed = _to_int(raw)
+        if isinstance(parsed, Coerced):
+            return parsed
+        if reject_negative and parsed < 0:
+            return invalid(raw, CoerceReason.EXPECTED_NON_NEGATIVE_INT)
+        if zero is not None and parsed == 0:
+            return _valid(zero)
+        if non_positive is not None and parsed <= 0:
+            return _valid(non_positive)
+        if minimum is not None and parsed < minimum:
+            return _clamped(raw, minimum, CoerceReason.BELOW_MINIMUM, minimum)
+        if maximum is not None and parsed > maximum:
+            return _clamped(raw, maximum, CoerceReason.ABOVE_MAXIMUM, maximum)
+        return _valid(parsed)
+
+    return coerce
+
+
+def optional_int_coercer(*, non_positive_means_none: bool = True) -> Coercer:
+    """Coerce to ``int | None`` where a non-positive value spells "no limit"."""
+
+    def coerce(raw: object) -> Coerced:
+        parsed = _to_int(raw)
+        if isinstance(parsed, Coerced):
+            return parsed
+        if non_positive_means_none and parsed <= 0:
+            return _valid(None)
+        return _valid(parsed)
+
+    return coerce
+
+
+def float_coercer(*, minimum: float | None = None, maximum: float | None = None) -> Coercer:
+    """Coerce to a **finite** float with optional clamping.
+
+    NaN and infinities are rejected rather than clamped: NaN compares false
+    against every bound, so it would sail through both checks and then silently
+    disable whatever threshold the field guards.
+    """
+
+    def coerce(raw: object) -> Coerced:
+        if raw is None:
+            return MISSING
+        if isinstance(raw, bool):
+            return invalid(raw, CoerceReason.EXPECTED_NUMBER)
+        candidate: int | float | str
+        if isinstance(raw, int | float):
+            candidate = raw
+        elif isinstance(raw, str):
+            normalized = raw.strip()
+            if not normalized:
+                return MISSING
+            candidate = normalized
+        else:
+            return invalid(raw, CoerceReason.EXPECTED_NUMBER)
+
+        try:
+            value = float(candidate)
+        except ValueError, OverflowError:
+            # ``OverflowError`` is the native-int path: YAML parses an
+            # arbitrarily long decimal into a Python ``int``, which ``float()``
+            # then refuses. A hand-edited YAML file must not crash the load.
+            return invalid(raw, CoerceReason.EXPECTED_NUMBER)
+
+        if not math.isfinite(value):
+            return invalid(raw, CoerceReason.EXPECTED_FINITE_NUMBER)
+        if minimum is not None and value < minimum:
+            return _clamped(raw, minimum, CoerceReason.BELOW_MINIMUM, minimum)
+        if maximum is not None and value > maximum:
+            return _clamped(raw, maximum, CoerceReason.ABOVE_MAXIMUM, maximum)
+        return _valid(value)
+
+    return coerce
+
+
+def choice_coercer(*, choices: Iterable[str]) -> Coercer:
+    """Coerce to one of *choices*, matched case-insensitively.
+
+    The **declared spelling** is returned, not the user's — ``zh-Hans`` stays
+    ``zh-Hans`` however it was typed, so downstream identity comparisons against
+    the canonical constant keep working.
+    """
+    canonical: dict[str, str] = {}
+    for choice in choices:
+        folded = choice.casefold()
+        if folded in canonical:
+            msg = f"Choices collide under case folding: {canonical[folded]!r} and {choice!r}"
+            raise ValueError(msg)
+        canonical[folded] = choice
+
+    def coerce(raw: object) -> Coerced:
+        if raw is None:
+            return MISSING
+        if not isinstance(raw, str):
+            return invalid(raw, CoerceReason.EXPECTED_TEXT)
+        normalized = raw.strip()
+        if not normalized:
+            return MISSING
+        found = canonical.get(normalized.casefold())
+        if found is None:
+            return invalid(raw, CoerceReason.NOT_A_CHOICE, choices=tuple(sorted(canonical.values())))
+        return _valid(found)
+
+    return coerce
+
+
+def text_coercer(*, strip: bool = True) -> Coercer:
+    """Coerce to a plain string. Empty means "unset", not "empty string"."""
+
+    def coerce(raw: object) -> Coerced:
+        if raw is None:
+            return MISSING
+        if not isinstance(raw, str):
+            return invalid(raw, CoerceReason.EXPECTED_TEXT)
+        value = raw.strip() if strip else raw
+        if not value.strip():
+            return MISSING
+        return _valid(value)
+
+    return coerce

chrys/foundation/config/context.py

@@ -0,0 +1,34 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Evaluation context: what the loader needs to know that is not a setting.
+
+Some project-layer checks cannot be decided from the stored value alone. The
+transient-retry budget is the case that forces this: a stored ``None`` means
+"use the frontend's policy default", which is 7 in the TUI and 15 in headless,
+so the *same* project value of 10 is a loosening for one frontend and a
+tightening for the other. Comparing raw fields would silently apply the wrong
+verdict in headless.
+
+This lives in its own module so both :mod:`chrys.foundation.config.spec` (which
+types the comparator) and the loader can import it without a cycle through
+``settings``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class EvalContext:
+    """Frontend policy in force for one ``load_settings`` call.
+
+    Must be passed explicitly at load time, not patched in afterwards: the
+    project layer is evaluated *during* the load, so a value substituted later
+    would arrive after the verdict it was meant to inform. The initial load,
+    ``SettingsReload``, a workspace change and a session restore all have to
+    pass the same context, or one project file yields different verdicts at
+    different points in a single process's life.
+    """
+
+    frontend_default_max_transient_retries: int

chrys/foundation/config/env_file.py

@@ -0,0 +1,141 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Atomic updates for Chrys's process-independent configuration dotenv."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+from chrys.foundation.platform.files import atomic_write_text, digest_bytes
+from chrys.foundation.util.lock import FileLock
+
+
+def config_env_path() -> Path:
+    """Return the canonical Chrys configuration dotenv path."""
+    from chrys.foundation.platform import get_platform
+
+    return get_platform().config_dir / ".env"
+
+
+def env_lock_path(path: Path) -> Path:
+    """Return the sibling lock path guarding the dotenv file at *path*.
+
+    Shared with the readers that have to prove they read what they are about to
+    delete from: two spellings of this name would be two locks over one file,
+    which is the same as no lock at all.
+    """
+    return path.with_name(f"{path.name}.lock")
+
+
+def _validate_single_line(name: str, value: str) -> None:
+    if "\r" in value or "\n" in value:
+        msg = f"{name} must not contain newline characters"
+        raise ValueError(msg)
+
+
+def _dotenv_key(line: str) -> str | None:
+    """Return the key from a parseable dotenv assignment line."""
+    stripped = line.strip()
+    if not stripped or stripped.startswith("#") or "=" not in stripped:
+        return None
+    if stripped.startswith("export "):
+        stripped = stripped.removeprefix("export ").lstrip()
+    key = stripped.split("=", 1)[0].strip()
+    if not key or any(char.isspace() for char in key):
+        return None
+    return key
+
+
+def _line_ending(line: str) -> str:
+    if line.endswith("\r\n"):
+        return "\r\n"
+    if line.endswith(("\r", "\n")):
+        return line[-1]
+    return ""
+
+
+def _quoted_assignment(key: str, value: str) -> str:
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'{key}="{escaped}"'
+
+
+def update_env_file(
+    updates: dict[str, str],
+    *,
+    remove_keys: Iterable[str] = (),
+    expect_fingerprint: str | None = None,
+) -> bool:
+    """Atomically merge and remove dotenv keys while preserving unrelated lines.
+
+    Removal matches the way the OS reads the file, not the way the line is
+    spelled: on Windows the environment is case-insensitive, so a lowercase
+    ``chrys_theme`` line answers for ``CHRYS_THEME`` and must go when that key
+    goes — otherwise the migration leaves behind a spelling that keeps
+    overriding the user's document. On POSIX the spellings are distinct keys
+    and only the exact one is touched.
+
+    Args:
+        expect_fingerprint: Refuse the whole edit unless the file still digests
+            to this. Checked *inside* the lock, which is the only place the
+            check means anything — a caller comparing beforehand has merely
+            moved its own race. Removals are the reason it exists: they delete
+            lines chosen from an earlier read of this file, and between the two
+            the file may have grown a key that read never saw.
+
+    Returns whether the file was left in the requested state; ``False`` only
+    ever means the fingerprint did not match, and nothing was written.
+    """
+    # Function-scope import: this module is imported by ``settings``, which
+    # ``env_layers`` imports in turn.
+    from chrys.foundation.config.env_layers import canonical_env_name
+
+    removals = tuple(remove_keys)
+    for key, value in updates.items():
+        _validate_single_line("dotenv key", key)
+        _validate_single_line(f"dotenv value for {key}", value)
+    for key in removals:
+        _validate_single_line("dotenv key", key)
+
+    path = config_env_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lock_path = env_lock_path(path)
+    removal_set = {canonical_env_name(key) for key in removals}
+
+    with FileLock(lock_path):
+        # One read answers both "is this still the file we were promised" and
+        # "what is in it". Digesting the path and then opening it is two reads,
+        # and a writer that does not take this lock — any text editor — can
+        # land between them: the check passes on the old bytes and the rewrite
+        # then strips keys out of the new ones. Digesting what was actually
+        # read leaves nothing between the two to lose.
+        raw = path.read_bytes() if path.is_file() else None
+        if expect_fingerprint is not None and digest_bytes(raw) != expect_fingerprint:
+            return False
+        existed = raw is not None
+        # ``newline=""`` is what the old text-mode read used, i.e. no newline
+        # translation, so decoding the bytes reproduces it exactly.
+        original = raw.decode("utf-8") if raw is not None else ""
+
+        found_updates: set[str] = set()
+        rewritten: list[str] = []
+        for line in original.splitlines(keepends=True):
+            key = _dotenv_key(line)
+            if key is not None and canonical_env_name(key) in removal_set:
+                continue
+            if key in updates:
+                found_updates.add(key)
+                rewritten.append(f"{_quoted_assignment(key, updates[key])}{_line_ending(line)}")
+            else:
+                rewritten.append(line)
+
+        payload = "".join(rewritten)
+        appended = [key for key in updates if key not in found_updates and canonical_env_name(key) not in removal_set]
+        if appended:
+            if payload and not payload.endswith(("\r", "\n")):
+                payload += "\n"
+            payload += "".join(f"{_quoted_assignment(key, updates[key])}\n" for key in appended)
+
+        if not existed or payload != original:
+            atomic_write_text(path, payload)
+        return True