@deftai/directive-content 0.55.1 → 0.56.0

package/scripts/_triage_scope_mutations.py

@@ -0,0 +1,337 @@
+"""``task triage:scope`` wrapper-verb helpers (D14c / #1182).
+
+Provides programmatic helpers consumed by ``scripts/_triage_scope_cli.py``
+for the long-tail tuning surface that wraps the typed-policy edit so
+the operator doesn't hand-edit ``vbrief/PROJECT-DEFINITION.vbrief.json``:
+
+* :func:`add_label_to_scope` -- delegate to
+  ``triage_subscribe.subscribe(label=...)`` (idempotent; merges into an
+  existing labels.any-of rule when present; atomic; audit-logged).
+* :func:`add_milestone_to_scope` -- delegate to
+  ``triage_subscribe.subscribe(milestone=...)`` (idempotent; atomic;
+  audit-logged).
+* :func:`add_label_to_ignores` -- delegate to
+  ``triage_scope_drift.add_ignore(label=...)`` (idempotent; atomic;
+  audit-logged since D14c).
+* :func:`compute_diff_from_upstream` -- read-only partition of an
+  upstream label / milestone set into ``subscribed / ignored / neither``.
+  Test-injectable via the ``upstream_labels`` / ``upstream_milestones``
+  kwargs so the unit tests do not need network access.
+* :func:`fetch_upstream_labels_and_milestones` -- ``gh api`` fetcher
+  used by the CLI when no test-injection happens. Pure REST (per
+  ``templates/agent-prompt-preamble.md`` §5); no GraphQL.
+
+Kept in a sibling module to ``scripts/triage_scope.py`` so the parent
+module stays under the 1000-line MUST cap from ``coding/coding.md``.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Mutation verb wrappers
+# ---------------------------------------------------------------------------
+
+
+def add_label_to_scope(
+    project_root: Path,
+    label: str,
+    *,
+    actor: str | None = None,
+) -> tuple[bool, str]:
+    """``task triage:scope -- --add-label=<L>`` -- delegate to subscribe()."""
+    if not isinstance(label, str) or not label.strip():
+        raise ValueError(f"label must be a non-empty string; got {label!r}")
+    from triage_subscribe import subscribe
+
+    return subscribe(project_root, label=label, actor=actor)
+
+
+def add_milestone_to_scope(
+    project_root: Path,
+    milestone: str,
+    *,
+    actor: str | None = None,
+) -> tuple[bool, str]:
+    """``task triage:scope -- --add-milestone=<M>`` -- delegate to subscribe()."""
+    if not isinstance(milestone, str) or not milestone.strip():
+        raise ValueError(f"milestone must be a non-empty string; got {milestone!r}")
+    from triage_subscribe import subscribe
+
+    return subscribe(project_root, milestone=milestone, actor=actor)
+
+
+def add_label_to_ignores(
+    project_root: Path,
+    label: str,
+) -> tuple[bool, str]:
+    """``task triage:scope -- --ignore-label=<L>`` -- delegate to add_ignore().
+
+    The older ``task triage:scope-drift -- --ignore-label`` continues to
+    work as an alias for the same typed field; both surfaces call into
+    :func:`triage_scope_drift.add_ignore` and so share the audit-log
+    contract introduced in D14c (#1182).
+    """
+    if not isinstance(label, str) or not label.strip():
+        raise ValueError(f"label must be a non-empty string; got {label!r}")
+    from triage_scope_drift import add_ignore
+
+    return add_ignore(project_root, label=label)
+
+
+# ---------------------------------------------------------------------------
+# --diff-from-upstream report
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class DiffReport:
+    """Partition of an upstream label / milestone set vs typed policy.
+
+    Each set captures the names that fall into one of three buckets:
+
+    * ``subscribed`` -- the name appears in ``plan.policy.triageScope[]``
+      (any-of / all-of / milestone-rule)
+    * ``ignored`` -- the name appears in
+      ``plan.policy.triageScopeIgnores[]`` (label / milestone single-key
+      or rule-shaped author entries)
+    * ``neither`` -- the name appears upstream but neither in scope nor
+      in ignores; this is the operator's TODO list ("decide -- subscribe
+      or ignore?").
+
+    Fields are ``frozenset[str]`` to honour the ``frozen=True`` dataclass
+    contract -- mutable ``set`` fields on a frozen dataclass are a
+    documented footgun (the wrapper is hashable, the fields are not).
+    """
+
+    subscribed_labels: frozenset[str] = field(default_factory=frozenset)
+    ignored_labels: frozenset[str] = field(default_factory=frozenset)
+    neither_labels: frozenset[str] = field(default_factory=frozenset)
+    subscribed_milestones: frozenset[str] = field(default_factory=frozenset)
+    ignored_milestones: frozenset[str] = field(default_factory=frozenset)
+    neither_milestones: frozenset[str] = field(default_factory=frozenset)
+    repo: str = ""
+
+
+def compute_diff_from_upstream(
+    project_root: Path,
+    *,
+    upstream_labels: set[str],
+    upstream_milestones: set[str],
+    repo: str = "",
+) -> DiffReport:
+    """Partition upstream labels / milestones into subscribed / ignored / neither.
+
+    Pure: never mutates state. Inputs are injected so unit tests can
+    skip network access. The CLI invokes
+    :func:`fetch_upstream_labels_and_milestones` to populate them.
+    """
+    from triage_scope import resolve_scope_ignores, resolve_scope_rules
+    from triage_scope_drift import _subscribed_labels, _subscribed_milestones
+
+    rules = resolve_scope_rules(project_root)
+    ignores = resolve_scope_ignores(project_root)
+
+    sub_labels = _subscribed_labels(rules)
+    sub_ms = _subscribed_milestones(rules)
+    ign_labels = ignores.get("labels", set())
+    ign_ms = ignores.get("milestones", set())
+
+    subscribed_labels: set[str] = set()
+    ignored_labels: set[str] = set()
+    neither_labels: set[str] = set()
+    for name in upstream_labels:
+        if not isinstance(name, str) or not name:
+            continue
+        if name in sub_labels:
+            subscribed_labels.add(name)
+        elif name in ign_labels:
+            ignored_labels.add(name)
+        else:
+            neither_labels.add(name)
+
+    subscribed_milestones: set[str] = set()
+    ignored_milestones: set[str] = set()
+    neither_milestones: set[str] = set()
+    for name in upstream_milestones:
+        if not isinstance(name, str) or not name:
+            continue
+        if name in sub_ms:
+            subscribed_milestones.add(name)
+        elif name in ign_ms:
+            ignored_milestones.add(name)
+        else:
+            neither_milestones.add(name)
+
+    return DiffReport(
+        subscribed_labels=frozenset(subscribed_labels),
+        ignored_labels=frozenset(ignored_labels),
+        neither_labels=frozenset(neither_labels),
+        subscribed_milestones=frozenset(subscribed_milestones),
+        ignored_milestones=frozenset(ignored_milestones),
+        neither_milestones=frozenset(neither_milestones),
+        repo=repo,
+    )
+
+
+def render_diff_report(report: DiffReport) -> str:
+    """Render a :class:`DiffReport` as a human-readable text block.
+
+    Format::
+
+        triage:scope --diff-from-upstream (repo: deftai/directive)
+        Labels:
+          subscribed (1): bug
+          ignored    (1): wontfix
+          neither    (2): adoption-blocker, urgent
+        Milestones:
+          subscribed (0): -
+          ignored    (0): -
+          neither    (1): v2.0-blocker
+    """
+
+    def _fmt(bucket: frozenset[str]) -> str:
+        if not bucket:
+            return "-"
+        return ", ".join(sorted(bucket))
+
+    lines: list[str] = []
+    repo_suffix = f" (repo: {report.repo})" if report.repo else ""
+    lines.append(f"triage:scope --diff-from-upstream{repo_suffix}")
+    lines.append("Labels:")
+    lines.append(
+        f"  subscribed ({len(report.subscribed_labels)}): {_fmt(report.subscribed_labels)}"
+    )
+    lines.append(
+        f"  ignored    ({len(report.ignored_labels)}): {_fmt(report.ignored_labels)}"
+    )
+    lines.append(
+        f"  neither    ({len(report.neither_labels)}): {_fmt(report.neither_labels)}"
+    )
+    lines.append("Milestones:")
+    lines.append(
+        f"  subscribed ({len(report.subscribed_milestones)}): "
+        f"{_fmt(report.subscribed_milestones)}"
+    )
+    lines.append(
+        f"  ignored    ({len(report.ignored_milestones)}): "
+        f"{_fmt(report.ignored_milestones)}"
+    )
+    lines.append(
+        f"  neither    ({len(report.neither_milestones)}): "
+        f"{_fmt(report.neither_milestones)}"
+    )
+    if report.neither_labels or report.neither_milestones:
+        lines.append("")
+        lines.append(
+            "To act on 'neither' items: task triage:scope -- --add-label=<L> / "
+            "--add-milestone=<M> / --ignore-label=<L>"
+        )
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Upstream fetcher (gh REST)
+# ---------------------------------------------------------------------------
+
+
+def fetch_upstream_labels_and_milestones(
+    repo: str,
+    *,
+    binary: str = "gh",
+) -> tuple[set[str], set[str]]:
+    """Fetch upstream open milestones + every label name via ``gh api`` (REST).
+
+    Two ``gh api`` calls (paginated REST per
+    ``templates/agent-prompt-preamble.md`` §5 -- never GraphQL). Returns
+    ``(labels, milestones)`` as string sets.
+
+    Raises :class:`RuntimeError` when ``gh`` is unavailable, the repo is
+    malformed, or the upstream returns non-list payloads. Callers should
+    catch and surface a human-readable error.
+    """
+    if not isinstance(repo, str) or "/" not in repo:
+        raise RuntimeError(
+            f"--repo must be 'owner/name'; got {repo!r}. Pass --repo OR set "
+            "$DEFT_TRIAGE_REPO."
+        )
+
+    labels = _fetch_names_via_gh(
+        binary,
+        f"repos/{repo}/labels?per_page=100",
+        name_field="name",
+    )
+    milestones = _fetch_names_via_gh(
+        binary,
+        f"repos/{repo}/milestones?per_page=100&state=open",
+        name_field="title",
+    )
+    return labels, milestones
+
+
+def _fetch_names_via_gh(binary: str, path: str, *, name_field: str) -> set[str]:
+    try:
+        proc = subprocess.run(  # noqa: S603 -- intentional gh invocation
+            [binary, "api", "--paginate", path],
+            check=False,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            timeout=30,
+        )
+    except FileNotFoundError as exc:
+        raise RuntimeError(
+            f"`{binary}` not found on PATH -- install GitHub CLI to use "
+            "`task triage:scope -- --diff-from-upstream`."
+        ) from exc
+    except subprocess.TimeoutExpired as exc:
+        raise RuntimeError(
+            f"`{binary} api {path}` timed out after 30s -- check your network."
+        ) from exc
+
+    if proc.returncode != 0:
+        raise RuntimeError(
+            f"`{binary} api {path}` failed (exit {proc.returncode}): "
+            f"{proc.stderr.strip() or proc.stdout.strip()}"
+        )
+
+    out = proc.stdout.strip()
+    if not out:
+        return set()
+    # `gh api --paginate` concatenates JSON arrays; the result is either
+    # a single array or several arrays concatenated. We tolerate both
+    # shapes (array-of-objects, or whitespace-separated arrays) by
+    # parsing one JSON document at a time via a streaming decoder.
+    decoder = json.JSONDecoder()
+    idx = 0
+    names: set[str] = set()
+    text = out
+    while idx < len(text):
+        # Skip leading whitespace between concatenated documents.
+        while idx < len(text) and text[idx].isspace():
+            idx += 1
+        if idx >= len(text):
+            break
+        try:
+            obj, consumed = decoder.raw_decode(text, idx)
+        except json.JSONDecodeError as exc:
+            raise RuntimeError(
+                f"`{binary} api {path}` returned non-JSON output: {exc}"
+            ) from exc
+        idx = consumed
+        if not isinstance(obj, list):
+            raise RuntimeError(
+                f"`{binary} api {path}` returned a non-list payload "
+                f"({type(obj).__name__}); REST expected."
+            )
+        for item in obj:
+            if not isinstance(item, dict):
+                continue
+            value = item.get(name_field)
+            if isinstance(value, str) and value:
+                names.add(value)
+    return names

package/scripts/_triage_scope_renderers.py

@@ -0,0 +1,207 @@
+"""Rule renderers + vBRIEF reference extractor for ``scripts/triage_scope.py``.
+
+Extracted from ``scripts/triage_scope.py`` so the parent module stays
+under the 1000-line MUST cap from ``coding/coding.md`` once D14 (#1133)
+landed the milestone rule type and the ``triageScopeIgnores[]``
+foundation. The public surface lives in ``triage_scope``; this module
+is the renderer + vBRIEF-reference helper only.
+
+Companion module: scripts/triage_scope.py (re-exports the names below
+for back-compat with existing call sites and tests).
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+
+def extract_referenced_issues(
+    project_root: Path | None = None,
+    *,
+    lifecycle_folders: tuple[str, ...] = (
+        "proposed",
+        "pending",
+        "active",
+        "completed",
+        "cancelled",
+    ),
+) -> dict[str, set[int]]:
+    """Walk ``vbrief/<folder>/*.vbrief.json`` and pull referenced issue numbers.
+
+    Returns ``{"any": {...}, "active": {...}}`` -- the per-scope sets
+    consumed by the ``referenced-by-vbrief`` evaluator. Used by
+    ``triage:scope --list`` to surface how the consumer's vBRIEF graph
+    feeds the subscription.
+    """
+    root = (project_root or Path.cwd()) / "vbrief"
+    any_set: set[int] = set()
+    active_set: set[int] = set()
+    if not root.is_dir():
+        return {"any": any_set, "active": active_set}
+    for folder in lifecycle_folders:
+        folder_path = root / folder
+        if not folder_path.is_dir():
+            continue
+        for vbrief_path in folder_path.glob("*.vbrief.json"):
+            try:
+                data = json.loads(vbrief_path.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError):
+                continue
+            plan = data.get("plan") if isinstance(data, dict) else None
+            if not isinstance(plan, dict):
+                continue
+            refs = plan.get("references") or []
+            if not isinstance(refs, list):
+                continue
+            for ref in refs:
+                if not isinstance(ref, dict):
+                    continue
+                if ref.get("type") != "x-vbrief/github-issue":
+                    continue
+                uri = ref.get("uri", "")
+                if not isinstance(uri, str):
+                    continue
+                tail = uri.rstrip("/").rsplit("/", 1)[-1]
+                if tail.isdigit():
+                    n = int(tail)
+                    any_set.add(n)
+                    if folder == "active":
+                        active_set.add(n)
+    return {"any": any_set, "active": active_set}
+
+
+def render_list(
+    rules: Iterable[dict[str, Any]],
+    *,
+    subscription_hash_fn: Any,
+    project_root: Path | None = None,
+    is_default: bool = False,
+) -> str:
+    """Return the human-readable ``triage:scope --list`` recap.
+
+    Format:
+
+        triage:scope effective rules (N):
+          1. all-open
+          2. labels any-of=[bug, regression]
+          3. explicit-watch:
+               - #1234  (<note>)
+               - #5678  (<note>)
+        subscription-hash: <hex>
+
+    A leading ``(default applied)`` annotation is added when the rule
+    set is the framework default (``plan.policy.triageScope`` unset).
+    Per Decision 4, ``explicit-watch`` entries always print their note
+    so future operators understand why a specific issue was pinned.
+
+    ``subscription_hash_fn`` is the parent module's hash callable
+    (passed in to avoid a circular import).
+    """
+    rules = list(rules)
+    lines: list[str] = []
+    header = f"triage:scope effective rules ({len(rules)}):"
+    if is_default:
+        header += " (default applied -- plan.policy.triageScope unset)"
+    lines.append(header)
+    for i, rule in enumerate(rules, start=1):
+        lines.extend(_render_rule(i, rule))
+    lines.append(f"subscription-hash: {subscription_hash_fn(rules)}")
+    return "\n".join(lines)
+
+
+def render_ignores(ignores: Iterable[dict[str, Any]] | None) -> str:
+    """Render the ``plan.policy.triageScopeIgnores[]`` block (D14c / #1182).
+
+    Empty / missing list renders as the canonical ``(none)`` line so the
+    operator can distinguish ``ran, no ignores`` from ``ran, ignores
+    not surfaced``. The output is grouped by ignore-entry kind (label /
+    milestone / author) so a long ignore-list stays scannable.
+    """
+    entries = list(ignores or [])
+    lines: list[str] = [
+        f"triage:scope ignores ({len(entries)} entries):",
+    ]
+    if not entries:
+        lines.append("  (none) -- task triage:scope -- --ignore-label=<L> to add")
+        return "\n".join(lines)
+    labels: list[str] = []
+    milestones: list[str] = []
+    authors: list[str] = []
+    other: list[str] = []
+    for entry in entries:
+        if not isinstance(entry, dict):
+            other.append(repr(entry))
+            continue
+        rule = entry.get("rule")
+        if rule == "author":
+            any_of = entry.get("any-of") or []
+            if isinstance(any_of, list):
+                authors.extend(
+                    str(name)
+                    for name in any_of
+                    if isinstance(name, str) and name
+                )
+            continue
+        label = entry.get("label")
+        if isinstance(label, str) and label:
+            labels.append(label)
+            continue
+        milestone = entry.get("milestone")
+        if isinstance(milestone, str) and milestone:
+            milestones.append(milestone)
+            continue
+        other.append(repr(entry))
+    if labels:
+        lines.append(f"  labels:     {sorted(labels)}")
+    if milestones:
+        lines.append(f"  milestones: {sorted(milestones)}")
+    if authors:
+        lines.append(f"  authors:    {sorted(authors)}")
+    if other:
+        lines.append(f"  unrecognised: {other}")
+    return "\n".join(lines)
+
+
+def _render_rule(idx: int, rule: dict[str, Any]) -> list[str]:
+    kind = rule.get("rule", "<unknown>")
+    if kind == "all-open":
+        return [f"  {idx}. all-open"]
+    if kind == "labels":
+        if "any-of" in rule:
+            return [f"  {idx}. labels any-of={sorted(rule['any-of'])}"]
+        if "all-of" in rule:
+            return [f"  {idx}. labels all-of={sorted(rule['all-of'])}"]
+        return [f"  {idx}. labels (malformed)"]
+    if kind == "milestone":
+        # D14 (#1133) v1 exact-match + D14b (#1181) any-of / is-open
+        # variants render distinctly so the operator can confirm which
+        # branch their subscription actually uses.
+        if "name" in rule:
+            return [f"  {idx}. milestone name={rule.get('name', '?')!r}"]
+        if "any-of" in rule:
+            raw = rule.get("any-of") or []
+            return [
+                f"  {idx}. milestone any-of={sorted(raw) if isinstance(raw, list) else raw}"
+            ]
+        if rule.get("is-open") is True:
+            return [f"  {idx}. milestone is-open=true (currently-open upstream)"]
+        return [f"  {idx}. milestone (malformed)"]
+    if kind in {"opened-since", "updated-since"}:
+        return [f"  {idx}. {kind} duration={rule.get('duration', '?')}"]
+    if kind == "referenced-by-vbrief":
+        return [f"  {idx}. referenced-by-vbrief scope={rule.get('scope', '?')}"]
+    if kind == "sliced-from":
+        return [f"  {idx}. sliced-from scope={rule.get('scope', '?')}"]
+    if kind == "explicit-watch":
+        out = [f"  {idx}. explicit-watch:"]
+        for entry in rule.get("issues", []):
+            if not isinstance(entry, dict):
+                continue
+            n = entry.get("n")
+            note = entry.get("note", "")
+            out.append(f"       - #{n}  ({note})")
+        return out
+    return [f"  {idx}. {kind} (unknown rule type)"]