@deftai/directive-content 0.59.0 → 0.60.0

package/scripts/_triage_scope_mutations.py

@@ -1,337 +0,0 @@
-"""``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

@@ -1,207 +0,0 @@
-"""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)"]