@deftai/directive-content 0.59.0 → 0.61.0

package/scripts/issue_emit.py

@@ -1,670 +0,0 @@
-#!/usr/bin/env python3
-r"""issue_emit.py -- Emit GitHub issues FROM scope vBRIEFs (the write path).
-
-This is the symmetric reverse of :mod:`scripts.issue_ingest`. Where
-``task issue:ingest`` reads a GitHub issue and materialises a scope vBRIEF,
-``task issue:emit`` reads one or more scope vBRIEFs and files GitHub
-issue(s), then records the resulting issue URL back into each source
-vBRIEF's ``plan.references[]`` as an ``x-vbrief/github-issue`` entry with
-``TrustLevel: external``. Together the two verbs close the
-vBRIEF <-> GitHub-issue trust loop (#1274 Change 2 / epic #1284).
-
-Modes:
-    uv run python scripts/issue_emit.py <vbrief-path>
-        File ONE issue for the named vBRIEF and write the URL back into it.
-    uv run python scripts/issue_emit.py --umbrella <glob> [<glob> ...]
-        File ONE umbrella issue with a checklist of the matched vBRIEFs and
-        write the umbrella URL back into EVERY matched vBRIEF.
-    uv run python scripts/issue_emit.py --per-vbrief <glob> [<glob> ...]
-        File one issue per matched vBRIEF.
-
-Flags:
-    --dry-run         Print the plan of issues that WOULD be filed; make no
-                      forge write and no on-disk vBRIEF mutation.
-    --repo OWNER/REPO Target repo (highest precedence; falls back to
-                      $DEFT_PROJECT_REPO / git remote detection).
-    --project-root    Consumer project root for repo / glob anchoring.
-    --title           Umbrella issue title override (--umbrella mode only).
-    --json            Emit a machine-readable JSON summary instead of prose.
-
-Network honour:
-    ``DEFT_NO_NETWORK=1`` is treated identically to ``--dry-run`` -- a plan
-    is printed, no issue is filed, and no source vBRIEF is mutated on disk.
-
-Idempotency:
-    A source vBRIEF that already carries a matching ``x-vbrief/github-issue``
-    reference is detected and skipped rather than re-filed, so a re-run does
-    not create duplicate issues.
-
-All ``gh`` invocations route through :func:`scripts.scm.call` (#1145 / N5)
-so the SCM boundary holds; the issue body is passed via
-``gh issue create --body-file`` (written as pathlib UTF-8) rather than an
-inline ``--body`` so non-ASCII narrative glyphs survive the round-trip.
-
-Exit codes:
-    0 -- emit completed (including dry-run / no-network plans and pure-skip)
-    2 -- usage / configuration / forge error
-
-Story: #1274 Change 2 (task issue:emit); epic #1284.
-"""
-
-from __future__ import annotations
-
-import argparse
-import contextlib
-import glob as globlib
-import json
-import os
-import re
-import sys
-import tempfile
-from collections.abc import Callable
-from pathlib import Path
-from typing import Any
-
-# Make sibling scripts importable both when run as __main__ and when imported
-# by tests that pre-populate sys.path with the ``scripts/`` directory.
-sys.path.insert(0, str(Path(__file__).resolve().parent))
-
-import scm  # noqa: E402 -- sibling-first path insertion above is intentional
-from _project_context import resolve_project_repo, resolve_project_root  # noqa: E402
-from _stdio_utf8 import reconfigure_stdio  # noqa: E402
-
-reconfigure_stdio()
-
-# --- Constants --------------------------------------------------------------
-
-#: Canonical reference type recorded on a source vBRIEF after a successful
-#: emit. Matches ``conventions/references.md`` and the
-#: ``EXTERNAL_REFERENCE_TYPES`` set in ``scripts/_vbrief_build.py``.
-GITHUB_ISSUE_REF_TYPE = "x-vbrief/github-issue"
-
-#: TrustLevel stamped on the emitted reference. An issue filed from a
-#: vBRIEF lives on the external forge, so it is ``external`` (the same
-#: default ``reference_with_default_trust`` would assign).
-EXTERNAL_TRUST_LEVEL = "external"
-
-#: Extracts the browser issue URL from ``gh issue create`` stdout. gh prints
-#: the created issue URL (e.g. ``https://github.com/o/r/issues/42``) as the
-#: final line of stdout on success.
-_ISSUE_URL_RE = re.compile(r"https?://\S+?/issues/\d+")
-
-
-class IssueEmitError(RuntimeError):
-    """Raised when filing a GitHub issue through the scm shim fails."""
-
-
-# --- vBRIEF helpers ---------------------------------------------------------
-
-
-def load_vbrief(path: Path) -> dict:
-    """Read and parse a vBRIEF JSON file (UTF-8)."""
-    data: Any = json.loads(path.read_text(encoding="utf-8"))
-    return data if isinstance(data, dict) else {}
-
-
-def write_vbrief(path: Path, data: dict) -> None:
-    """Write a vBRIEF dict back to disk as pretty-printed UTF-8 JSON.
-
-    Uses ``ensure_ascii=False`` so non-ASCII narrative glyphs round-trip as
-    real UTF-8 bytes (``task verify:encoding`` flags mojibake / BOM, and a
-    locale-default write would risk both on Windows hosts).
-    """
-    path.write_text(
-        json.dumps(data, indent=2, ensure_ascii=False) + "\n",
-        encoding="utf-8",
-    )
-
-
-def vbrief_title(data: dict) -> str:
-    """Resolve a human title for a vBRIEF.
-
-    Prefers ``plan.title``; falls back to ``vBRIEFInfo.description`` and then
-    a generic placeholder so a malformed vBRIEF still produces a usable issue
-    title rather than an empty string.
-    """
-    plan = data.get("plan", {}) if isinstance(data, dict) else {}
-    title = plan.get("title") if isinstance(plan, dict) else None
-    if isinstance(title, str) and title.strip():
-        return title.strip()
-    info = data.get("vBRIEFInfo", {}) if isinstance(data, dict) else {}
-    desc = info.get("description", "") if isinstance(info, dict) else ""
-    if isinstance(desc, str) and desc.strip():
-        return desc.strip()
-    return "Untitled vBRIEF"
-
-
-def existing_github_issue_ref(data: dict) -> str | None:
-    """Return the first ``x-vbrief/github-issue`` reference URI, or None.
-
-    Used for idempotency: a vBRIEF that already carries a github-issue
-    reference has already been tracked, so ``emit`` skips it instead of
-    filing a duplicate. Returns the empty string when a matching reference
-    exists but carries no URI (still a positive "already tracked" signal).
-    """
-    if not isinstance(data, dict):
-        return None
-    plan = data.get("plan", {})
-    refs = plan.get("references", []) if isinstance(plan, dict) else []
-    for ref in refs:
-        if isinstance(ref, dict) and ref.get("type") == GITHUB_ISSUE_REF_TYPE:
-            uri = ref.get("uri") or ref.get("url")
-            return uri if isinstance(uri, str) and uri else ""
-    return None
-
-
-def add_github_issue_reference(data: dict, url: str) -> dict:
-    """Append an external github-issue reference to ``plan.references[]``.
-
-    Mutates ``data`` in place (and returns it for convenience). The appended
-    entry is the canonical ``{uri, type, TrustLevel}`` shape required by the
-    #1274 acceptance criteria.
-    """
-    plan = data.setdefault("plan", {})
-    refs = plan.setdefault("references", [])
-    refs.append(
-        {
-            "uri": url,
-            "type": GITHUB_ISSUE_REF_TYPE,
-            "TrustLevel": EXTERNAL_TRUST_LEVEL,
-        }
-    )
-    return data
-
-
-# --- Issue body rendering ---------------------------------------------------
-
-
-def render_issue_body(data: dict) -> str:
-    """Render a GitHub issue body from a vBRIEF's narratives.
-
-    Sections, in order: Description, Acceptance (plan-level narrative plus
-    per-item ``narrative.Acceptance`` bullets), and Traces. Empty sections
-    are omitted. A vBRIEF with no usable narrative still yields a non-empty
-    body naming the scope so ``gh issue create`` never receives an empty
-    ``--body-file``.
-    """
-    plan = data.get("plan", {}) if isinstance(data, dict) else {}
-    narratives = plan.get("narratives", {}) if isinstance(plan, dict) else {}
-    if not isinstance(narratives, dict):
-        narratives = {}
-
-    parts: list[str] = []
-
-    desc = narratives.get("Description")
-    if isinstance(desc, str) and desc.strip():
-        parts.append("## Description\n\n" + desc.strip())
-
-    acceptance_lines: list[str] = []
-    plan_acceptance = narratives.get("Acceptance")
-    if isinstance(plan_acceptance, str) and plan_acceptance.strip():
-        acceptance_lines.append(plan_acceptance.strip())
-    for item in plan.get("items", []) if isinstance(plan, dict) else []:
-        if not isinstance(item, dict):
-            continue
-        item_narrative = item.get("narrative", {})
-        acc = item_narrative.get("Acceptance") if isinstance(item_narrative, dict) else None
-        if isinstance(acc, str) and acc.strip():
-            item_title = str(item.get("title", "")).strip()
-            if item_title:
-                acceptance_lines.append(f"- **{item_title}**: {acc.strip()}")
-            else:
-                acceptance_lines.append(f"- {acc.strip()}")
-    if acceptance_lines:
-        parts.append("## Acceptance\n\n" + "\n".join(acceptance_lines))
-
-    traces = narratives.get("Traces")
-    if isinstance(traces, str) and traces.strip():
-        parts.append("## Traces\n\n" + traces.strip())
-
-    if not parts:
-        return f"Scope vBRIEF: {vbrief_title(data)}\n"
-    return "\n\n".join(parts) + "\n"
-
-
-def render_umbrella_body(entries: list[tuple[str, dict]], *, intro: str | None = None) -> str:
-    """Render an umbrella issue body with a checklist of tracked vBRIEFs.
-
-    ``entries`` is a list of ``(relative-or-display-path, vbrief-data)``
-    tuples. Each becomes an unchecked task-list item naming the vBRIEF title
-    and its path so the umbrella reads as a roadmap.
-    """
-    lines: list[str] = []
-    if intro:
-        lines.append(intro.strip())
-        lines.append("")
-    lines.append("## Tracked vBRIEFs")
-    lines.append("")
-    for display_path, data in entries:
-        lines.append(f"- [ ] {vbrief_title(data)} (`{display_path}`)")
-    return "\n".join(lines) + "\n"
-
-
-# --- Forge interaction ------------------------------------------------------
-
-
-def file_issue(
-    repo: str,
-    title: str,
-    body: str,
-    *,
-    scm_call: Callable[..., Any] | None = None,
-) -> str:
-    """File a single GitHub issue via the scm shim and return its URL.
-
-    The body is written to a temporary UTF-8 file and passed through
-    ``gh issue create --body-file`` so non-ASCII glyphs survive (an inline
-    ``--body`` risks codepage corruption on Windows hosts). The call routes
-    through :func:`scripts.scm.call` with ``source="github-issue"`` so the
-    #1145 SCM boundary holds, and forces ``encoding="utf-8",
-    errors="replace"`` per the #1366 safe-capture rule.
-
-    Raises :class:`IssueEmitError` on a non-zero exit or when no issue URL
-    can be parsed from stdout.
-    """
-    # Resolve the binding at call time (not as a default arg) so tests that
-    # monkeypatch ``issue_emit.scm.call`` take effect.
-    if scm_call is None:
-        scm_call = scm.call
-    fd, tmp_name = tempfile.mkstemp(suffix=".md", prefix="deft-issue-emit-")
-    os.close(fd)
-    body_path = Path(tmp_name)
-    try:
-        body_path.write_text(body, encoding="utf-8")
-        result = scm_call(
-            "github-issue",
-            "issue",
-            [
-                "create",
-                "--repo",
-                repo,
-                "--title",
-                title,
-                "--body-file",
-                str(body_path),
-            ],
-            timeout=60,
-            encoding="utf-8",
-            errors="replace",
-        )
-    finally:
-        with contextlib.suppress(OSError):
-            body_path.unlink()
-
-    if result.returncode != 0:
-        stderr = (result.stderr or "").strip()
-        raise IssueEmitError(f"gh issue create failed (exit {result.returncode}): {stderr}")
-    stdout = (result.stdout or "").strip()
-    match = _ISSUE_URL_RE.search(stdout)
-    if match:
-        return match.group(0)
-    if stdout:
-        return stdout
-    raise IssueEmitError("gh issue create succeeded but emitted no issue URL on stdout")
-
-
-# --- Emit actions -----------------------------------------------------------
-
-
-def emit_single(
-    path: Path,
-    *,
-    repo: str,
-    scm_call: Callable[..., Any] | None = None,
-    no_network: bool = False,
-    display_path: str | None = None,
-) -> dict:
-    """File one issue for a single vBRIEF and write the URL back into it.
-
-    Returns an action dict with ``result`` one of ``"created"`` /
-    ``"dryrun"`` / ``"skipped"``. ``no_network`` (dry-run or DEFT_NO_NETWORK)
-    prints nothing here -- it returns a ``"dryrun"`` action and makes no
-    forge write and no on-disk mutation. A vBRIEF that already carries a
-    github-issue reference returns ``"skipped"`` (idempotency).
-    """
-    shown = display_path or str(path)
-    data = load_vbrief(path)
-    existing = existing_github_issue_ref(data)
-    if existing is not None:
-        return {
-            "result": "skipped",
-            "vbrief": shown,
-            "url": existing or None,
-            "title": vbrief_title(data),
-        }
-
-    title = vbrief_title(data)
-    if no_network:
-        return {
-            "result": "dryrun",
-            "vbrief": shown,
-            "url": None,
-            "title": title,
-        }
-
-    body = render_issue_body(data)
-    url = file_issue(repo, title, body, scm_call=scm_call)
-    add_github_issue_reference(data, url)
-    write_vbrief(path, data)
-    return {"result": "created", "vbrief": shown, "url": url, "title": title}
-
-
-def emit_per_vbrief(
-    paths: list[Path],
-    *,
-    repo: str,
-    scm_call: Callable[..., Any] | None = None,
-    no_network: bool = False,
-    display_paths: list[str] | None = None,
-) -> list[dict]:
-    """File one issue per matched vBRIEF (delegates to :func:`emit_single`)."""
-    shown = display_paths or [str(p) for p in paths]
-    actions: list[dict] = []
-    for path, disp in zip(paths, shown, strict=True):
-        actions.append(
-            emit_single(
-                path,
-                repo=repo,
-                scm_call=scm_call,
-                no_network=no_network,
-                display_path=disp,
-            )
-        )
-    return actions
-
-
-def emit_umbrella(
-    paths: list[Path],
-    *,
-    repo: str,
-    scm_call: Callable[..., Any] | None = None,
-    no_network: bool = False,
-    title: str | None = None,
-    display_paths: list[str] | None = None,
-) -> dict:
-    """File ONE umbrella issue tracking the matched vBRIEFs.
-
-    Writes the umbrella URL back into every matched vBRIEF that does not
-    already carry a github-issue reference. When EVERY matched vBRIEF is
-    already tracked, the umbrella is treated as a no-op (``"skipped"``) so a
-    re-run does not file a duplicate roadmap issue.
-
-    Returns an action dict with ``result`` one of ``"created"`` /
-    ``"dryrun"`` / ``"skipped"`` and a ``vbriefs`` list of per-file outcomes.
-    """
-    shown = display_paths or [str(p) for p in paths]
-    loaded: list[tuple[Path, str, dict]] = []
-    for path, disp in zip(paths, shown, strict=True):
-        loaded.append((path, disp, load_vbrief(path)))
-
-    pending = [
-        (path, disp, data) for path, disp, data in loaded if existing_github_issue_ref(data) is None
-    ]
-    already = [
-        {"vbrief": disp, "result": "skipped"}
-        for path, disp, data in loaded
-        if existing_github_issue_ref(data) is not None
-    ]
-
-    umbrella_title = title or _default_umbrella_title(loaded)
-
-    if not pending:
-        return {
-            "result": "skipped",
-            "url": None,
-            "title": umbrella_title,
-            "vbriefs": already,
-        }
-
-    if no_network:
-        return {
-            "result": "dryrun",
-            "url": None,
-            "title": umbrella_title,
-            "vbriefs": [{"vbrief": disp, "result": "dryrun"} for _path, disp, _data in pending]
-            + already,
-        }
-
-    body = render_umbrella_body([(disp, data) for _path, disp, data in pending])
-    url = file_issue(repo, umbrella_title, body, scm_call=scm_call)
-
-    written: list[dict] = []
-    for path, disp, data in pending:
-        add_github_issue_reference(data, url)
-        write_vbrief(path, data)
-        written.append({"vbrief": disp, "result": "created"})
-
-    return {
-        "result": "created",
-        "url": url,
-        "title": umbrella_title,
-        "vbriefs": written + already,
-    }
-
-
-def _default_umbrella_title(loaded: list[tuple[Path, str, dict]]) -> str:
-    """Synthesise an umbrella title when the caller did not supply one."""
-    count = len(loaded)
-    noun = "vBRIEF" if count == 1 else "vBRIEFs"
-    return f"Umbrella: {count} tracked {noun}"
-
-
-# --- Path expansion ---------------------------------------------------------
-
-
-def expand_patterns(patterns: list[str], *, root: Path | None = None) -> list[Path]:
-    """Expand glob ``patterns`` into a de-duplicated, ordered list of paths.
-
-    Patterns are resolved relative to ``root`` (the project root) when given
-    and not already absolute. A pattern with no glob matches that names an
-    existing file is taken literally so ``emit <one-file>`` works without a
-    wildcard. Document order is preserved; duplicates are dropped.
-    """
-    seen: set[str] = set()
-    out: list[Path] = []
-    for pattern in patterns:
-        candidate = pattern
-        if root is not None and not os.path.isabs(pattern):
-            candidate = str(root / pattern)
-        matches = sorted(globlib.glob(candidate))
-        if not matches and Path(candidate).exists():
-            matches = [candidate]
-        for match in matches:
-            resolved = str(Path(match).resolve())
-            if resolved in seen:
-                continue
-            seen.add(resolved)
-            out.append(Path(match))
-    return out
-
-
-# --- CLI --------------------------------------------------------------------
-
-
-def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        description=(
-            "File GitHub issue(s) from scope vBRIEFs and record the issue "
-            "URL back into each vBRIEF's references[] (#1274 Change 2)."
-        ),
-    )
-    parser.add_argument(
-        "patterns",
-        nargs="*",
-        help="vBRIEF path (single mode) or glob(s) (--umbrella / --per-vbrief)",
-    )
-    mode = parser.add_mutually_exclusive_group()
-    mode.add_argument(
-        "--umbrella",
-        action="store_true",
-        help="File ONE umbrella issue with a checklist of matched vBRIEFs",
-    )
-    mode.add_argument(
-        "--per-vbrief",
-        action="store_true",
-        help="File one issue per matched vBRIEF",
-    )
-    parser.add_argument(
-        "--title",
-        default=None,
-        help="Umbrella issue title (--umbrella mode only)",
-    )
-    parser.add_argument(
-        "--dry-run",
-        action="store_true",
-        help="Print the plan without filing issues or mutating vBRIEFs",
-    )
-    parser.add_argument(
-        "--json",
-        action="store_true",
-        help="Emit a machine-readable JSON summary instead of prose",
-    )
-    parser.add_argument(
-        "--repo",
-        default=None,
-        help="GitHub repo OWNER/REPO (highest precedence; beats env / git remote)",
-    )
-    parser.add_argument(
-        "--project-root",
-        default=None,
-        help="Consumer project root used for repo detection and glob anchoring",
-    )
-    return parser
-
-
-def _is_no_network(dry_run: bool) -> bool:
-    """Return True when network access is disabled (dry-run or env opt-out)."""
-    return dry_run or os.environ.get("DEFT_NO_NETWORK") == "1"
-
-
-def _print_summary(summary: dict, *, as_json: bool) -> None:
-    if as_json:
-        print(json.dumps(summary, ensure_ascii=False, indent=2))
-        return
-    mode = summary["mode"]
-    no_network = summary["no_network"]
-    banner = "issue:emit plan (no network)" if no_network else "issue:emit"
-    print(f"{banner} -- mode: {mode}")
-    if mode == "umbrella":
-        action = summary["umbrella"]
-        verb = {
-            "created": "FILED umbrella",
-            "dryrun": "WOULD FILE umbrella",
-            "skipped": "SKIP umbrella (already tracked)",
-        }[action["result"]]
-        url = f" -> {action['url']}" if action.get("url") else ""
-        print(f"  {verb}: {action['title']}{url}")
-        for child in action["vbriefs"]:
-            print(f"    - {child['result'].upper():8} {child['vbrief']}")
-    else:
-        for action in summary["actions"]:
-            verb = {
-                "created": "FILED",
-                "dryrun": "WOULD FILE",
-                "skipped": "SKIP (already tracked)",
-            }[action["result"]]
-            url = f" -> {action['url']}" if action.get("url") else ""
-            print(f"  {verb:22} {action['vbrief']}{url}")
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = build_parser()
-    args = parser.parse_args(argv)
-
-    if not args.patterns:
-        parser.error("Provide a vBRIEF path or glob(s) to emit")
-
-    if args.title and not args.umbrella:
-        parser.error("--title is only valid with --umbrella")
-
-    project_root = resolve_project_root(args.project_root)
-    paths = expand_patterns(args.patterns, root=project_root)
-    if not paths:
-        print(
-            f"Error: no vBRIEF files matched {args.patterns!r}.",
-            file=sys.stderr,
-        )
-        return 2
-
-    no_network = _is_no_network(args.dry_run)
-
-    # Repo is only required for a real (network) filing. Dry-run / no-network
-    # plans never call the forge, so a missing repo is not fatal there.
-    repo = ""
-    if not no_network:
-        repo = resolve_project_repo(args.repo, project_root=project_root) or ""
-        if not repo:
-            print(
-                "Error: could not detect repo. Pass --repo OWNER/NAME, set "
-                "$DEFT_PROJECT_REPO, or run from the consumer repo (#538).",
-                file=sys.stderr,
-            )
-            return 2
-
-    display = [_display_path(p, project_root) for p in paths]
-
-    try:
-        if args.umbrella:
-            action = emit_umbrella(
-                paths,
-                repo=repo,
-                no_network=no_network,
-                title=args.title,
-                display_paths=display,
-            )
-            summary = {
-                "mode": "umbrella",
-                "no_network": no_network,
-                "umbrella": action,
-            }
-        elif args.per_vbrief:
-            actions = emit_per_vbrief(
-                paths,
-                repo=repo,
-                no_network=no_network,
-                display_paths=display,
-            )
-            summary = {
-                "mode": "per-vbrief",
-                "no_network": no_network,
-                "actions": actions,
-            }
-        else:
-            if len(paths) != 1:
-                print(
-                    "Error: single mode expects exactly one vBRIEF; matched "
-                    f"{len(paths)}. Use --umbrella or --per-vbrief for globs.",
-                    file=sys.stderr,
-                )
-                return 2
-            action = emit_single(
-                paths[0],
-                repo=repo,
-                no_network=no_network,
-                display_path=display[0],
-            )
-            summary = {
-                "mode": "single",
-                "no_network": no_network,
-                "actions": [action],
-            }
-    except IssueEmitError as exc:
-        print(f"Error: {exc}", file=sys.stderr)
-        return 2
-
-    _print_summary(summary, as_json=args.json)
-    return 0
-
-
-def _display_path(path: Path, project_root: Path | None) -> str:
-    """Return ``path`` relative to the project root when possible."""
-    if project_root is not None:
-        try:
-            return str(path.resolve().relative_to(project_root.resolve()))
-        except ValueError:
-            pass
-    return str(path)
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())