ww-agentic-workflows 1.0.0.dev3__py3-none-any.whl

ww/config/values.py

@@ -0,0 +1,223 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Shared YAML value validation for workflow configuration parsing."""
+
+from __future__ import annotations
+
+from typing import Any, cast, get_args
+
+from ww.contracts import StepRole
+from ww.errors import ConfigurationError
+from ww.extensions import is_extension_reference
+from ww.validation import (
+    NAME_PATTERN as _NAME,
+)
+from ww.validation import (
+    expect_mapping,
+    expect_nonempty_string,
+    expect_normalized_name,
+    reject_unknown_keys,
+)
+from ww.workflow_config import ALL, ALL_NAMES, NameFilter
+
+
+def _mapping(value: Any, path: str) -> dict[str, Any]:
+    return expect_mapping(value, path, error=ConfigurationError)
+
+
+def _named_entry(
+    mapping: dict[str, Any],
+    path: str,
+    *,
+    allowed: set[str] | None = None,
+    ignored: set[str] | None = None,
+) -> dict[str, Any]:
+    """Expand ``name: description`` shorthand into the shared action shape."""
+    if "name" in mapping:
+        return mapping
+    candidates = [key for key in mapping if ignored is None or key not in ignored]
+    if not candidates:
+        return mapping
+    shorthand_name = candidates[0]
+    if allowed is not None and shorthand_name in allowed:
+        return mapping
+    shorthand_description = mapping[shorthand_name]
+    if not isinstance(shorthand_name, str) or not shorthand_name.strip():
+        raise ConfigurationError(f"{path} shorthand name must be a non-empty string")
+    if shorthand_description is not None and not isinstance(shorthand_description, str):
+        raise ConfigurationError(
+            f"{path} shorthand description must be a string or null"
+        )
+    if "description" in mapping:
+        raise ConfigurationError(
+            f"{path} cannot combine shorthand and explicit descriptions"
+        )
+    normalized = dict(mapping)
+    del normalized[shorthand_name]
+    normalized["name"] = shorthand_name
+    if shorthand_description is not None:
+        normalized["description"] = shorthand_description
+    return normalized
+
+
+def _only(mapping: dict[str, Any], allowed: set[str], path: str) -> None:
+    reject_unknown_keys(mapping, allowed, path, error=ConfigurationError)
+
+
+def _name(mapping: dict[str, Any], path: str) -> str:
+    return _required_string(mapping, "name", path)
+
+
+def _required_string(mapping: dict[str, Any], key: str, path: str) -> str:
+    return expect_normalized_name(
+        mapping.get(key), f"{path}.{key}", error=ConfigurationError
+    )
+
+
+def _nonempty_string(mapping: dict[str, Any], key: str, path: str) -> str:
+    return expect_nonempty_string(
+        mapping.get(key), f"{path}.{key}", error=ConfigurationError
+    )
+
+
+def _optional_string(mapping: dict[str, Any], key: str, path: str) -> str | None:
+    if key not in mapping:
+        return None
+    return _nonempty_string(mapping, key, path)
+
+
+def _optional_bool(mapping: dict[str, Any], key: str, path: str) -> bool | None:
+    if key not in mapping:
+        return None
+    value = mapping[key]
+    if not isinstance(value, bool):
+        raise ConfigurationError(f"{path}.{key} must be true or false")
+    return value
+
+
+def _optional_agent(mapping: dict[str, Any], key: str, path: str) -> str | None:
+    value = _optional_string(mapping, key, path)
+    if value == "auto":
+        raise ConfigurationError(f"{path}.{key} must not be 'auto'")
+    return value
+
+
+def _role(mapping: dict[str, Any], path: str) -> StepRole | None:
+    """The declared ``role``, or ``None`` when the step inherits one."""
+    if "role" not in mapping:
+        return None
+    value = mapping["role"]
+    if value not in get_args(StepRole):
+        raise ConfigurationError(f"{path}.role must be manager or worker")
+    return cast(StepRole, value)
+
+
+def _subagents(mapping: dict[str, Any], path: str) -> bool | None:
+    """The declared ``subagents``, or ``None`` when the step inherits it.
+
+    ``false`` means whoever performs the step, manager or worker, spawns no
+    subagents for anything; who performs it is ``role``'s business.
+    """
+    if "subagents" not in mapping:
+        return None
+    value = mapping["subagents"]
+    if not isinstance(value, bool):
+        raise ConfigurationError(f"{path}.subagents must be true or false")
+    return value
+
+
+def _optional_name(mapping: dict[str, Any], key: str, path: str) -> str | None:
+    if key not in mapping:
+        return None
+    return _required_string(mapping, key, path)
+
+
+def _profile(mapping: dict[str, Any], path: str) -> dict[str, str | None]:
+    value = mapping.get("profile")
+    if value is None:
+        return {"profile": None, "profile_description": None}
+    if isinstance(value, str):
+        if not value.strip() or not _NAME.fullmatch(value):
+            raise ConfigurationError(f"{path}.profile must be a normalized name")
+        return {"profile": value, "profile_description": None}
+    profile = _mapping(value, f"{path}.profile")
+    _only(profile, {"name", "description"}, f"{path}.profile")
+    name = _optional_name(profile, "name", f"{path}.profile")
+    description = _optional_string(profile, "description", f"{path}.profile")
+    if name is None and description is None:
+        raise ConfigurationError(f"{path}.profile requires name or description")
+    return {"profile": name, "profile_description": description}
+
+
+def _description(value: Any, path: str) -> str:
+    if value is None:
+        return ""
+    if not isinstance(value, str):
+        raise ConfigurationError(f"{path}.description must be a string")
+    return value
+
+
+def _description_items(value: Any, path: str) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        return (value,)
+    if not isinstance(value, list) or not all(
+        isinstance(item, str) and item for item in value
+    ):
+        raise ConfigurationError(
+            f"{path}.description must be a string or list of strings"
+        )
+    return tuple(value)
+
+
+def _required_list(mapping: dict[str, Any], key: str, path: str) -> list[Any]:
+    value = mapping.get(key)
+    if not isinstance(value, list):
+        raise ConfigurationError(f"{path}.{key} must be a list")
+    return value
+
+
+def _reference_or_name(value: str) -> bool:
+    return bool(_NAME.fullmatch(value)) or is_extension_reference(value)
+
+
+def _string_list(value: Any, path: str) -> tuple[str, ...]:
+    if not isinstance(value, list) or not all(
+        isinstance(item, str) and _reference_or_name(item) for item in value
+    ):
+        raise ConfigurationError(f"{path} must be a list of normalized names")
+    return tuple(value)
+
+
+def _name_filter(value: Any, path: str, *, empty: NameFilter) -> NameFilter:
+    """Parse a ``workflows`` or ``steps`` filter: ``"*"`` or a list of names.
+
+    A step name may be a ``/``-separated path. ``empty`` is what ``[]``
+    means where the filter is written: every name for a hook, none for a
+    rule group.
+    """
+    if value == ALL_NAMES:
+        return ALL
+    if not isinstance(value, list):
+        raise ConfigurationError(
+            f'{path} must be "*" or a list of names'
+            + (f" (write [{value}] for one name)" if isinstance(value, str) else "")
+        )
+    if ALL_NAMES in value:
+        raise ConfigurationError(
+            f'{path} cannot mix "*" with names; write "*" alone for all'
+        )
+    if not all(
+        isinstance(item, str)
+        and item
+        and all(_NAME.fullmatch(segment) for segment in item.split("/"))
+        for item in value
+    ):
+        raise ConfigurationError(f'{path} must be "*" or a list of normalized names')
+    return NameFilter.of(value) if value else empty
+
+
+def _unique(values: Any, label: str) -> None:
+    items = tuple(values)
+    if len(set(items)) != len(items):
+        raise ConfigurationError(f"duplicate {label} name")

ww/config_files.py

@@ -0,0 +1,191 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""The names and locations of ww's configuration files.
+
+``ww.yaml`` describes what workflows do and
+``ww.json`` how the tools around them behave. Each comes in
+three levels, applied top to bottom so a lower level wins:
+
+1. user: ``ww.{yaml,json}`` in the user's configuration
+   directory, shared by every project of the user;
+2. repo: ``ww.{yaml,json}`` in the project root;
+3. local: ``ww.local.{yaml,json}`` next to the repo files,
+   kept out of version control.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from pathlib import Path
+
+FILE_STEM = "ww"
+WORKFLOWS_FILE = f"{FILE_STEM}.yaml"
+SETTINGS_FILE = f"{FILE_STEM}.json"
+LOCAL_WORKFLOWS_FILE = f"{FILE_STEM}.local.yaml"
+LOCAL_SETTINGS_FILE = f"{FILE_STEM}.local.json"
+# The rule-automation store: ww-owned derived knowledge at the project root,
+# committed so every checkout shares it, never part of a step's change set.
+RULE_AUTOMATION_FILE = "ww-rule-automation.json"
+# Rule groups ``ww rules add --group`` and ``ww rules filter`` write, imported
+# by the repo file so that file is never rewritten; ww owns this one.
+RULES_IMPORT_FILE = "ww-rules.yaml"
+# What ``ww setup apply`` writes: an import file for the repo level, and one
+# for the local level, which stays out of version control.
+SETUP_IMPORT_FILE = "ww-setup.yaml"
+LOCAL_SETUP_IMPORT_FILE = "ww-setup.local.yaml"
+# The .gitignore patterns ``init`` adds; they also cover local files a local
+# configuration imports, such as ``git.ww.local.yaml``.
+LOCAL_IGNORE_PATTERNS = (
+    f"*{LOCAL_WORKFLOWS_FILE}",
+    f"*{LOCAL_SETTINGS_FILE}",
+    LOCAL_SETUP_IMPORT_FILE,
+)
+# The files under ``.ww`` a team commits: what ww learned about the project.
+# Everything else there is one checkout's state. Existing ``.gitignore`` lines
+# are never touched; the operator's own re-includes stay as they are.
+SHARED_RUNTIME_FILES = ("project.md",)
+# The .gitignore lines ``init`` writes for ``.ww``. Git cannot re-include a
+# file inside an ignored directory, so the directory's contents are ignored
+# rather than the directory itself, and each shared file is then re-included.
+RUNTIME_IGNORE_LINES = (
+    ".ww/*",
+    *(f"!.ww/{name}" for name in SHARED_RUNTIME_FILES),
+)
+# The lines that ignore ``.ww`` whole, as an operator may write them; ``init``
+# replaces them with :data:`RUNTIME_IGNORE_LINES`, since a directory ignored
+# whole cannot have files re-included.
+WHOLE_RUNTIME_IGNORE_LINES = (".ww/", ".ww", "/.ww", "/.ww/")
+
+
+def runtime_ignored(gitignore: str) -> bool:
+    """Whether a .gitignore's text already keeps ``.ww`` out, in any form."""
+    return bool(
+        {*WHOLE_RUNTIME_IGNORE_LINES, RUNTIME_IGNORE_LINES[0]}.intersection(
+            line.strip() for line in gitignore.splitlines()
+        )
+    )
+
+
+def newline_of(text: str) -> str:
+    """The line ending a text file uses: CRLF when it has one, else LF."""
+    return "\r\n" if "\r\n" in text else "\n"
+
+
+# Where the user level lives instead of the user's configuration directory.
+USER_DIR_VARIABLE = "WW_USER_CONFIG_DIR"
+
+
+@dataclass(frozen=True)
+class ConfigurationLevel:
+    """Where one level keeps one kind of configuration file."""
+
+    name: str
+    path: Path
+
+
+def user_directory() -> Path:
+    """The user level's directory, following XDG when it is configured."""
+    configured = os.environ.get(USER_DIR_VARIABLE)
+    if configured:
+        directory = Path(configured)
+    else:
+        base = os.environ.get("XDG_CONFIG_HOME")
+        directory = (Path(base) if base else Path.home() / ".config") / FILE_STEM
+    return directory
+
+
+# Configuration files read as if written, by resolved path; ``None`` reads as
+# absent. ``ww setup apply`` validates its plan this way, so checking a change
+# never touches the project.
+_STAGED: ContextVar[Mapping[Path, str | None] | None] = ContextVar(
+    "ww_staged_configuration", default=None
+)
+
+
+@contextmanager
+def staged_files(contents: Mapping[Path, str | None]) -> Iterator[None]:
+    """Read configuration files as if ``contents`` were written in place.
+
+    Only reads through :func:`read_configuration_file` and
+    :func:`configuration_file_exists` see the staged contents; nothing is
+    written.
+    """
+    token = _STAGED.set({path.resolve(): text for path, text in contents.items()})
+    try:
+        yield
+    finally:
+        _STAGED.reset(token)
+
+
+def read_configuration_file(path: Path) -> str:
+    """A configuration file's text, staged or on disk."""
+    staged = _STAGED.get()
+    if staged is not None and path.resolve() in staged:
+        text = staged[path.resolve()]
+        if text is None:
+            raise FileNotFoundError(f"no such file: {path}")
+        return text
+    return path.read_text(encoding="utf-8")
+
+
+def configuration_file_exists(path: Path) -> bool:
+    """Whether a configuration file is there, staged or on disk."""
+    staged = _STAGED.get()
+    if staged is not None and path.resolve() in staged:
+        return staged[path.resolve()] is not None
+    return path.is_file()
+
+
+def display_path(file: Path, base: Path) -> str:
+    """How messages name ``file``: from the repo root, from home, or in full."""
+    for root, prefix in ((base, ""), (Path.home(), "~/")):
+        try:
+            return prefix + str(file.relative_to(root))
+        except ValueError:
+            continue
+    return str(file)
+
+
+def _levels(
+    repo_file: Path, user_name: str, local_name: str
+) -> tuple[ConfigurationLevel, ...]:
+    """The user, repo, and local levels around ``repo_file``.
+
+    The user file shares the repo file's name, so a user directory that is
+    the project root itself contributes no separate level.
+    """
+    user = user_directory() / user_name
+    return (
+        *(
+            (ConfigurationLevel("user", user),)
+            if user.resolve() != repo_file.resolve()
+            else ()
+        ),
+        ConfigurationLevel("repo", repo_file),
+        ConfigurationLevel("local", repo_file.with_name(local_name)),
+    )
+
+
+def workflow_levels(repo_file: Path) -> tuple[ConfigurationLevel, ...]:
+    """The YAML levels around ``repo_file``, from user to local."""
+    return _levels(repo_file, WORKFLOWS_FILE, LOCAL_WORKFLOWS_FILE)
+
+
+def settings_levels(repo_file: Path) -> tuple[ConfigurationLevel, ...]:
+    """The JSON levels around ``repo_file``, from user to local."""
+    return _levels(repo_file, SETTINGS_FILE, LOCAL_SETTINGS_FILE)
+
+
+def project_settings_levels(directory: Path) -> tuple[ConfigurationLevel, ...]:
+    """The JSON levels a configured project carries in its own directory.
+
+    A project has a repo and a local level, like the root; the user level is
+    shared by every project of the user and is read once, at the root.
+    """
+    return (
+        ConfigurationLevel("repo", directory / SETTINGS_FILE),
+        ConfigurationLevel("local", directory / LOCAL_SETTINGS_FILE),
+    )

ww/config_writes.py

@@ -0,0 +1,264 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""File writes that ww makes to configuration, together or not at all.
+
+``ww rules add`` and ``ww setup apply`` plan their changes as
+:class:`FileWrite` values and apply them in a :class:`Transaction`, which puts
+every file back as it was when anything fails. ``ww rules add`` loads the
+configuration after writing; ``ww setup apply`` validates its plan in memory
+first and writes only once it is confirmed. The import file each command owns
+is added to a root file's ``imports`` with :func:`import_write`, which changes
+that one list and refuses when it cannot do so without touching anything else.
+
+A write goes through a symbolic link to the file it names and keeps that
+file's permissions, so a configuration file kept elsewhere stays linked.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from ww.errors import StateError
+
+
+@dataclass(frozen=True)
+class FileWrite:
+    """One file's new content, or ``None`` to delete it."""
+
+    path: Path
+    content: str | None
+
+
+class Transaction:
+    """Files written together and restored together when anything fails."""
+
+    def __init__(self) -> None:
+        self._saved: list[tuple[Path, bytes | None]] = []
+        self._created: list[Path] = []
+        self._done = False
+
+    def __enter__(self) -> Transaction:
+        return self
+
+    def __exit__(self, kind: object, error: object, trace: object) -> None:
+        if error is not None:
+            self.roll_back()
+
+    def apply(
+        self, writes: Iterable[FileWrite], directories: Iterable[Path] = ()
+    ) -> None:
+        """Write every change, or put back what was written and fail.
+
+        An ``OSError`` becomes a :class:`StateError` once the files are back.
+        """
+        try:
+            for directory in directories:
+                self._make_directory(directory)
+            for change in writes:
+                # A symbolic link stays one: its target is what changes.
+                path = change.path.resolve()
+                self._saved.append((path, path.read_bytes() if path.exists() else None))
+                if change.content is None:
+                    path.unlink()
+                else:
+                    self._make_directory(path.parent)
+                    atomic_write(path, change.content)
+        except OSError as error:
+            self.roll_back()
+            raise StateError(
+                f"cannot write {error.filename or 'a file'}: {error.strerror or error}"
+                "; nothing was written"
+            ) from error
+
+    def _make_directory(self, directory: Path) -> None:
+        missing = [
+            folder for folder in (directory, *directory.parents) if not folder.exists()
+        ]
+        for folder in reversed(missing):
+            folder.mkdir()
+            self._created.append(folder)
+
+    def roll_back(self) -> None:
+        if self._done:
+            return
+        self._done = True
+        for path, content in reversed(self._saved):
+            if content is None:
+                path.unlink(missing_ok=True)
+            else:
+                path.write_bytes(content)
+        for folder in reversed(self._created):
+            if folder.is_dir() and not any(folder.iterdir()):
+                folder.rmdir()
+
+
+def atomic_write(path: Path, content: str) -> None:
+    """Replace the file ``path`` names whole, keeping its permissions.
+
+    A symbolic link is written through to its target. The temporary file is
+    removed when the write fails.
+    """
+    target = path.resolve()
+    temporary = target.with_name(f".{target.name}.ww-tmp")
+    try:
+        temporary.write_text(content, encoding="utf-8")
+        if target.exists():
+            temporary.chmod(target.stat().st_mode & 0o7777)
+        temporary.replace(target)
+    except OSError:
+        temporary.unlink(missing_ok=True)
+        raise
+
+
+_WIDTH = 80
+_ITEM = re.compile(r"  -( |$)")
+_LONG_TEXT = 72
+_SHORT_LIST = 60
+
+
+class _Dumper(yaml.SafeDumper):
+    """Block style YAML a person would write, without anchors or ``null``."""
+
+    def ignore_aliases(self, data: Any) -> bool:
+        return True
+
+    def increase_indent(self, flow: bool = False, indentless: bool = False) -> None:
+        super().increase_indent(flow, False)
+
+
+def _represent_none(dumper: _Dumper, _: None) -> yaml.ScalarNode:
+    return dumper.represent_scalar("tag:yaml.org,2002:null", "")
+
+
+def _represent_str(dumper: _Dumper, text: str) -> yaml.ScalarNode:
+    style = "|" if "\n" in text else ">" if len(text) > _LONG_TEXT else None
+    return dumper.represent_scalar("tag:yaml.org,2002:str", text, style=style)
+
+
+def _is_short_scalar(item: Any) -> bool:
+    if isinstance(item, str):
+        return "\n" not in item and len(item) <= _SHORT_LIST
+    return isinstance(item, (bool, int, float))
+
+
+def _represent_list(dumper: _Dumper, items: list[Any]) -> yaml.SequenceNode:
+    inline = all(map(_is_short_scalar, items)) and len(str(items)) <= _SHORT_LIST
+    return dumper.represent_sequence("tag:yaml.org,2002:seq", items, flow_style=inline)
+
+
+_Dumper.add_representer(type(None), _represent_none)
+_Dumper.add_representer(str, _represent_str)
+_Dumper.add_representer(list, _represent_list)
+
+
+def _dump(value: Any) -> str:
+    return yaml.dump(  # type: ignore[no-any-return]
+        value,
+        Dumper=_Dumper,
+        sort_keys=False,
+        allow_unicode=True,
+        default_flow_style=False,
+        width=_WIDTH,
+    )
+
+
+def _section(key: Any, value: Any) -> str:
+    """One top-level key, with a blank line between the items of its list.
+
+    Every other line of a block list's item, block text included, is indented
+    deeper than the ``  - `` that starts the item.
+    """
+    lines = _dump({key: value}).splitlines(True)
+    if not isinstance(value, list):
+        return "".join(lines)
+    return "".join(
+        f"\n{line}" if index > 1 and _ITEM.match(line) else line
+        for index, line in enumerate(lines)
+    )
+
+
+def dump_yaml(value: dict[str, Any]) -> str:
+    """``value`` as readable YAML that loads back to the same data.
+
+    Mappings are written in block style, short scalar lists inline, long text
+    folded and multi-line text as a literal block. Top-level sections and the
+    items of a top-level list are separated by a blank line.
+    """
+    return "\n".join(_section(key, item) for key, item in value.items())
+
+
+def import_write(
+    root: Path, text: str, raw: dict[str, Any], entry: str, label: str
+) -> FileWrite:
+    """``root`` with ``entry`` added to its imports, and nothing else changed."""
+    updated = with_import(text, raw, entry)
+    imports = list(raw.get("imports") or [])
+    expected = {"imports": [*imports, entry]}
+    expected.update((key, value) for key, value in raw.items() if key != "imports")
+    if yaml.safe_load(updated) != expected:
+        raise StateError(
+            f"ww cannot add {entry} to the imports of {label} without changing "
+            "anything else; add it by hand and run the command again"
+        )
+    return FileWrite(root, updated)
+
+
+def with_import(text: str, raw: dict[str, Any], entry: str) -> str:
+    """``text`` with ``entry`` appended to its top-level ``imports`` list.
+
+    Without ``imports``, the list goes before the first top-level key, since
+    imports come before every key but ``extends``. An existing list gains one
+    line in block style, or one element in a one-line flow list.
+    """
+    lines = text.splitlines(keepends=True)
+    if lines and not lines[-1].endswith("\n"):
+        lines[-1] += "\n"
+    if "imports" not in raw:
+        index = next(
+            (
+                position
+                for position, line in enumerate(lines)
+                if line.strip() and not line.startswith(("#", "---", "%", " ", "\t"))
+            ),
+            len(lines),
+        )
+        return "".join([*lines[:index], f"imports:\n  - {entry}\n", *lines[index:]])
+    start = next(
+        (
+            position
+            for position, line in enumerate(lines)
+            # The top-level imports key, e.g. "imports:" or "imports :".
+            if re.match(r"imports\s*:", line)
+        ),
+        None,
+    )
+    if start is None:
+        return text
+    value = lines[start].split(":", 1)[1].split(" #", 1)[0].strip()
+    if value.startswith("[") and value.endswith("]"):
+        line = lines[start]
+        close = line.rindex("]")
+        separator = ", " if value[1:-1].strip() else ""
+        lines[start] = f"{line[:close]}{separator}{entry}{line[close:]}"
+        return "".join(lines)
+    if value:
+        return text
+    last = None
+    prefix = "  - "
+    for position in range(start + 1, len(lines)):
+        line = lines[position]
+        if not line.strip() or line.lstrip().startswith("#"):
+            continue
+        if line.lstrip().startswith("- ") and (line[0] in " \t-"):
+            last = position
+            prefix = line[: len(line) - len(line.lstrip())] + "- "
+            continue
+        break
+    if last is None:
+        return text
+    return "".join([*lines[: last + 1], f"{prefix}{entry}\n", *lines[last + 1 :]])