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

ww/output_adapters/rule_pages.py

@@ -0,0 +1,337 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Markdown for the rule commands: ``check``, ``rule`` and ``rules``.
+
+``ww check`` reads like the fix page a completion would produce, so a worker
+sees the same failures in the same shape before it completes.
+"""
+
+from __future__ import annotations
+
+from ww.instructions.commands import dispute_command
+from ww.instructions.models import CheckPreview
+from ww.output_adapters.markdown import (
+    Lines,
+    _append_section,
+    _document,
+    _fix_failures,
+    _waivers,
+)
+from ww.rule_conversion import StoreChange, scriptize_state
+from ww.rule_store import (
+    CheckEntry,
+    RuleAutomation,
+    describe_command,
+)
+from ww.rule_views import ListedRule, Orphans, RulesListing, RuleView
+from ww.workflow_config import RuleDefinition
+
+
+def _ids(ids: tuple[str, ...]) -> str:
+    return ", ".join(f"`{item}`" for item in ids)
+
+
+def render_check_preview(preview: CheckPreview) -> str:
+    lines: Lines = [f"# {preview.task_id} · check `{preview.step}`", ""]
+    if not preview.checks and not preview.judged:
+        lines.append(
+            "This step has no checks to run and no rules for a verifier to judge."
+        )
+        return _document(lines)
+    if preview.failures:
+        lines.extend(
+            [
+                f"## {len(preview.failures)} of {preview.checks} checks failed",
+                "",
+                "Completing now would be rejected for these checks, on the files "
+                "this step changed so far:",
+            ]
+        )
+        _fix_failures(lines, preview.failures)
+        lines.extend(
+            [
+                "",
+                "Fix the causes, or, when a check that already rejected a "
+                "completion is wrong for this change, dispute it:",
+                "",
+                "```console",
+                dispute_command(preview.task_id, assignment="<your-assignment-token>"),
+                "```",
+            ]
+        )
+    elif preview.checks:
+        lines.append(f"All checks pass ({preview.checks} run).")
+    others = [
+        (label, ids)
+        for label, ids in (
+            ("Passed", preview.passed),
+            (
+                "Not applicable (their globs match no changed file)",
+                preview.not_applicable,
+            ),
+        )
+        if ids
+    ]
+    if others:
+        lines.append("")
+        lines.extend(f"{label}: {_ids(ids)}." for label, ids in others)
+    if preview.judged:
+        lines.extend(
+            [
+                "",
+                f"Judged at completion: {_ids(preview.judged)}. A verifier, not "
+                "you, judges these rules after you complete.",
+            ]
+        )
+    for reason, waived in _waivers(preview.waived):
+        lines.extend(["", f"Waived by the operator ({_ids(tuple(waived))}): {reason}."])
+    if preview.all_files:
+        lines.extend(
+            [
+                "",
+                "There is no change set (no git), so the checks saw every file "
+                "of the project their globs select.",
+            ]
+        )
+    lines.extend(
+        [
+            "",
+            "Nothing was recorded: this does not count as an attempt, and the "
+            "checks' output was not kept.",
+        ]
+    )
+    return _document(lines)
+
+
+def render_rule_view(view: RuleView) -> str:
+    kind = {
+        "rule": "Rule",
+        "hook": "Hook check",
+        "derived": "Derived check",
+    }.get(view.kind, "Check")
+    lines: Lines = [f"# {kind} `{view.id}`", "", view.text]
+    facts: Lines = []
+    if view.paths:
+        facts.append(f"- Applies to: {', '.join(view.paths)}")
+    if view.source:
+        facts.append(f"- Rule file: {view.source}")
+    elif view.kind == "rule":
+        facts.append("- Written in the step's own `rules` list.")
+    elif view.kind == "hook":
+        facts.append("- A `before_complete` hook with `on_failure: fix`.")
+    elif view.kind == "derived":
+        facts.append(
+            "- An approved check from the rule-automation store, covering "
+            + _ids(view.covers)
+            + "."
+        )
+    if view.steps:
+        facts.append(f"- Steps of this task: {_ids(view.steps)}")
+    if view.command:
+        facts.append(f"- Command: `{view.command}`")
+        if view.assertion:
+            facts.append(f"- {view.assertion}")
+        if view.max_fixes is not None:
+            facts.append(f"- Fix rounds allowed: {view.max_fixes}")
+    elif view.kind == "rule":
+        facts.append("- No command: a verifier judges it when the step completes.")
+    if view.store_status:
+        store = f"- Rule-automation store: {view.store_status}"
+        if view.store_check:
+            store += f" (check `{view.store_check}`)"
+        facts.append(store)
+    elif view.kind == "rule" and not view.command:
+        facts.append("- Rule-automation store: nothing yet")
+    if view.interpretation:
+        facts.append(f"- Interpretation: {view.interpretation}")
+    if view.resolution:
+        facts.append(f"- Enforced in the current step as: {view.resolution}")
+    if view.text_hash:
+        facts.append(f"- Wording hash: {view.text_hash[:12]}")
+    lines.extend(["", *facts])
+    return _document(lines)
+
+
+def render_rules_listing(listing: RulesListing) -> str:
+    lines: Lines = ["# Rules"]
+    if not listing.groups and not listing.steps:
+        lines.extend(["", "No rules are declared."])
+        return _document(lines)
+    for group in listing.groups:
+        _append_section(lines, f"Group `{group.name}`")
+        filters = [
+            f"{label} {_ids(names.listed)}"
+            for label, names in (("workflows", group.workflows), ("steps", group.steps))
+            if not names.admits_all
+        ]
+        if group.workflows.admits_none or group.steps.admits_none:
+            scope = "only where a step names it"
+        elif filters:
+            scope = "; ".join(filters)
+        else:
+            scope = "every step"
+        lines.append(f"Applies to: {scope}.")
+        if group.origin != "configuration":
+            lines.append(f"Shipped by: {group.origin}.")
+        if group.hints:
+            lines.append(
+                "Verifier hints: "
+                + ", ".join(f"{key} {value}" for key, value in group.hints.items())
+                + "."
+            )
+        _rule_lines(lines, group.rules)
+    for step in listing.steps:
+        _append_section(lines, f"Step `{step.step}`")
+        if step.groups:
+            lines.append(f"Names the groups {_ids(step.groups)}.")
+        _rule_lines(lines, step.rules)
+    return _document(lines)
+
+
+# How a rule without a command is enforced when no store check runs for it.
+_JUDGED_STATES = {
+    "not_convertible": " (judged: declined for scriptizing)",
+    "rejected": " (judged: its check was rejected)",
+    "unscriptized": " (judged: not scriptized yet)",
+}
+
+
+def _rule_lines(lines: Lines, rules: tuple[ListedRule, ...]) -> None:
+    if not rules:
+        return
+    lines.append("")
+    for rule in rules:
+        scope = f" — {', '.join(rule.paths)}" if rule.paths else ""
+        check = (
+            " (checked by its command)"
+            if rule.has_check
+            else f" (checked by store check `{rule.store_check}`)"
+            if rule.store_check
+            else _JUDGED_STATES.get(rule.scriptize, "")
+        )
+        disputed = (
+            f" (disputed {rule.disputes} time{'s' if rule.disputes != 1 else ''})"
+            if rule.disputes
+            else ""
+        )
+        lines.append(f"- `{rule.id}`{scope} — {rule.summary}{check}{disputed}")
+
+
+def render_orphans(listed: Orphans, automation: RuleAutomation) -> str:
+    """The store entries ``ww rules prune`` would delete."""
+    if not listed:
+        return "The rule-automation store has no orphan entries.\n"
+    lines = ["Orphan entries in the rule-automation store:"]
+    lines.extend(
+        f"- rule {key[:12]} ({automation.rules[key].status}): "
+        f"{automation.rules[key].text}"
+        for key in listed.rules
+    )
+    lines.extend(
+        f"- check {name} ({automation.checks[name].status})" for name in listed.checks
+    )
+    return "\n".join(lines) + "\n"
+
+
+def render_convert_preview(
+    name: str,
+    rules: tuple[RuleDefinition, ...],
+    current: RuleAutomation,
+    change: StoreChange,
+) -> str:
+    """What ``ww rules convert`` would record, command in full."""
+    spec = change.automation.checks[name].spec
+    action = "replaces" if name in current.checks else "creates"
+    lines = [
+        f"Check {name} ({action} the store's entry): {describe_command(spec.command)}",
+    ]
+    if spec.command.assertion is not None:
+        lines.append(f"- output must be: {spec.command.assertion.describe()}")
+    lines.append(
+        "- config files: " + (", ".join(spec.config) if spec.config else "none")
+    )
+    lines.append(f"- proven: {'yes' if spec.proven else 'no'}")
+    lines.append(f"- covers {len(rules)} rule(s):")
+    _covered_rules(lines, rules, current)
+    _side_effects(lines, rules, current, change)
+    return "\n".join(lines) + "\n"
+
+
+def render_decline_preview(
+    rules: tuple[RuleDefinition, ...],
+    reason: str,
+    current: RuleAutomation,
+    change: StoreChange,
+) -> str:
+    """What ``ww rules decline`` would record."""
+    lines = [f"Rules to record as not convertible ({reason}):"]
+    _covered_rules(lines, rules, current)
+    _side_effects(lines, rules, current, change)
+    return "\n".join(lines) + "\n"
+
+
+def _covered_rules(
+    lines: Lines, rules: tuple[RuleDefinition, ...], current: RuleAutomation
+) -> None:
+    """Each rule with where it stands in the store now."""
+    for rule in rules:
+        entry = current.rules.get(rule.text_hash)
+        state: str = scriptize_state(current, rule)
+        if state == "converted" and entry is not None and entry.check:
+            state = f"converted by check {entry.check}"
+        lines.append(f"  - `{rule.id}`: {rule.summary} (now: {state})")
+
+
+def _side_effects(
+    lines: Lines,
+    rules: tuple[RuleDefinition, ...],
+    current: RuleAutomation,
+    change: StoreChange,
+) -> None:
+    """The store's other changes: moved rules, unscriptized ones, drops."""
+    ids = {rule.text_hash: rule.id for rule in rules}
+    for key, check in change.moved:
+        lines.append(f"- takes `{ids[key]}` out of check {check}")
+    for key in change.unscriptized:
+        lines.append(
+            f"- returns {_rule_name(current, key)} to not scriptized: no longer covered"
+        )
+    for check in change.dropped_checks:
+        status = current.checks[check].status
+        lines.append(f"- removes check {check} ({status}): it covers nothing more")
+    for check in change.dropped_revisions:
+        lines.append(f"- drops the pending revision of check {check}")
+
+
+def _rule_name(automation: RuleAutomation, key: str) -> str:
+    entry = automation.rules.get(key)
+    text = entry.text.splitlines()[0] if entry is not None and entry.text else ""
+    return f"rule {key[:12]}" + (f" ({text})" if text else "")
+
+
+def render_revoke_preview(name: str, check: CheckEntry) -> str:
+    """The check ``ww rules revoke`` would reject, as the operator reads it."""
+    spec = check.pending or check.spec
+    lines = [
+        f"Check {name} ({check.status}): {describe_command(spec.command)}",
+        f"- covers {len(spec.covers)} rule(s)",
+    ]
+    if check.approved_by is not None:
+        lines.append(f"- approved by {check.approved_by}")
+    if spec.config:
+        lines.append("- config files: " + ", ".join(spec.config))
+    return "\n".join(lines) + "\n"
+
+
+def render_revoked(name: str, rules: tuple[str, ...], config: tuple[str, ...]) -> str:
+    """What ``ww rules revoke`` changed, and what it left for the operator."""
+    listed = " (" + ", ".join(key[:12] for key in rules) + ")" if rules else ""
+    files = f" and the check's config files ({', '.join(config)})" if config else ""
+    lines = [
+        f"Revoked check {name}: it is rejected in the rule-automation store "
+        "and no longer runs.",
+        f"Rules rejected with it, judged by a verifier from now on: "
+        f"{len(rules)}{listed}",
+        f"Nothing else changed: the YAML and rule files{files} stay as they "
+        "are, for the operator to keep or remove.",
+    ]
+    return "\n".join(lines) + "\n"

ww/output_adapters/terminal.py

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Terminal presentation shared by init prompts and completion output."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+
+def terminal_accent(text: str) -> str:
+    if (
+        sys.stdout.isatty()
+        and "NO_COLOR" not in os.environ
+        and os.environ.get("TERM") != "dumb"
+    ):
+        return f"\033[1;36m{text}\033[0m"
+    return text
+
+
+def initialization_progress(percent: int) -> str:
+    return terminal_accent(f"[{str(percent).rjust(6, '.')}%]")

ww/package_updates.py

@@ -0,0 +1,167 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Compatible PyPI versions and cached notices for packaged installations."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import platform
+import sys
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
+from packaging.tags import sys_tags
+from packaging.utils import InvalidWheelFilename, parse_wheel_filename
+from packaging.version import InvalidVersion, Version
+
+from ww import __version__
+from ww.executable import ww_command
+from ww.updates import interval_seconds, state_path
+
+PACKAGE_NAME = "ww-agentic-workflows"
+PYPI_URL = f"https://pypi.org/pypi/{PACKAGE_NAME}/json"
+HTTP_TIMEOUT_SECONDS = 2.0
+MAX_RESPONSE_BYTES = 2_000_000
+
+
+@dataclass(frozen=True)
+class PackageUpdateNotice:
+    installed_version: str
+    available_version: str
+
+    def to_dict(self) -> dict[str, str]:
+        return asdict(self)
+
+    def render(self) -> str:
+        return (
+            "## A newer ww is available\n\n"
+            f"{self.installed_version} → {self.available_version}\n"
+            f"Run: `{ww_command()} upgrade`\n\n"
+            "This notice is shown once. `ww updates` prints it again.\n\n---\n\n"
+        )
+
+
+def allows_prereleases(installed: str, *, pre: bool = False) -> bool:
+    return pre or Version(installed).is_prerelease
+
+
+def latest_compatible(
+    data: dict[str, Any], installed: str, *, pre: bool = False
+) -> str | None:
+    """Select only usable, non-yanked releases newer than this installation."""
+    current = Version(installed)
+    releases = data.get("releases")
+    if not isinstance(releases, dict):
+        return None
+    candidates: list[Version] = []
+    supported_tags = set(sys_tags())
+    for text, files in releases.items():
+        try:
+            candidate = Version(text)
+        except (InvalidVersion, TypeError):
+            continue
+        if candidate <= current or (
+            candidate.is_prerelease and not allows_prereleases(installed, pre=pre)
+        ):
+            continue
+        if not isinstance(files, list):
+            continue
+        for file in files:
+            if not isinstance(file, dict) or file.get("yanked", False):
+                continue
+            try:
+                requirement = file.get("requires_python") or ""
+                if not SpecifierSet(requirement).contains(platform.python_version()):
+                    continue
+                if file.get("packagetype") == "bdist_wheel":
+                    _, _, _, wheel_tags = parse_wheel_filename(file["filename"])
+                    if not wheel_tags.intersection(supported_tags):
+                        continue
+                elif file.get("packagetype") != "sdist":
+                    continue
+            except (InvalidSpecifier, InvalidWheelFilename, KeyError, TypeError):
+                continue
+            candidates.append(candidate)
+            break
+    return str(max(candidates)) if candidates else None
+
+
+def fetch_releases() -> dict[str, Any] | None:
+    """Bound the network request; offline or malformed responses stay quiet."""
+    try:
+        request = Request(PYPI_URL, headers={"User-Agent": f"ww/{__version__}"})
+        with urlopen(request, timeout=HTTP_TIMEOUT_SECONDS) as response:
+            body = response.read(MAX_RESPONSE_BYTES + 1)
+        if len(body) > MAX_RESPONSE_BYTES:
+            return None
+        data = json.loads(body)
+    except (OSError, URLError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def package_state_path() -> Path:
+    # Keep separate installations and stable/prerelease preferences independent.
+    key = hashlib.sha256(f"{sys.prefix}:{__version__}".encode()).hexdigest()[:16]
+    return state_path().with_name(f"package-updates-{key}.json")
+
+
+def _load(path: Path) -> dict[str, Any]:
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _save(path: Path, data: dict[str, Any]) -> None:
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        temporary = path.with_suffix(".tmp")
+        temporary.write_text(json.dumps(data))
+        temporary.replace(path)
+    except OSError:
+        return
+
+
+def last_package_notice() -> PackageUpdateNotice | None:
+    data = _load(package_state_path())
+    available = data.get("available_version")
+    try:
+        if isinstance(available, str) and Version(available) > Version(__version__):
+            return PackageUpdateNotice(__version__, available)
+    except InvalidVersion:
+        pass
+    return None
+
+
+def pending_package_notice(*, force: bool = False) -> PackageUpdateNotice | None:
+    path = package_state_path()
+    data = _load(path)
+    now = datetime.now(timezone.utc)
+    try:
+        checked = datetime.fromisoformat(data["last_checked"])
+        due = (now - checked).total_seconds() >= interval_seconds()
+    except (KeyError, ValueError, TypeError):
+        due = True
+    if force or due:
+        releases = fetch_releases()
+        available = latest_compatible(releases, __version__) if releases else None
+        data.update(last_checked=now.isoformat(), available_version=available)
+        _save(path, data)
+    notice = last_package_notice()
+    if notice and (force or data.get("announced_version") != notice.available_version):
+        return notice
+    return None
+
+
+def mark_package_announced(notice: PackageUpdateNotice) -> None:
+    path = package_state_path()
+    data = _load(path)
+    data["announced_version"] = notice.available_version
+    _save(path, data)

ww/plan/__init__.py

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Public plan data and compilation API."""
+
+from ww.operations import ChildWorkflowRun, LoopBoundary, PlanOperation, WorkflowHandoff
+
+from .compiler import (
+    ExecutionHints,
+    PlanCompilationOptions,
+    WorkflowPlanCompiler,
+    compile_workflow_plan,
+)
+from .models import (
+    PlanItem,
+    PlannedCheck,
+    PlannedMode,
+    PlannedRule,
+    VerificationTarget,
+    WorkflowPlan,
+    number_step_paths,
+)
+
+__all__ = [
+    "ExecutionHints",
+    "ChildWorkflowRun",
+    "LoopBoundary",
+    "PlanOperation",
+    "PlanCompilationOptions",
+    "PlanItem",
+    "PlannedCheck",
+    "PlannedMode",
+    "PlannedRule",
+    "VerificationTarget",
+    "WorkflowPlan",
+    "WorkflowHandoff",
+    "WorkflowPlanCompiler",
+    "compile_workflow_plan",
+    "number_step_paths",
+]