@seanyao/roll 0.5.0 → 2.602.1

package/lib/roll-loop-story.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""
+roll-loop-story — compact per-story rollup for `roll loop story <ID>`.
+
+Loads the same event / cron / runs / git-merge sources as roll-loop-status,
+filters cycles to one story id (case-insensitive), and renders a single
+panel covering cycles count, span, duration, tokens, cost, model, PR list,
+and recent cycle lines.
+
+Usage:
+  roll loop story US-LOOP-004
+  roll loop story us-loop-004                # case-insensitive
+  roll loop story US-LOOP-004 --json         # machine-readable
+  roll loop story US-LOOP-004 --days 30      # widen window (default 30)
+
+Exit codes:
+  0 — at least one cycle found
+  2 — story id has no cycles in the event window
+"""
+from __future__ import annotations
+import argparse, importlib.util, json, os, sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List
+
+_LIB_DIR = os.path.dirname(os.path.realpath(__file__))
+
+# Reuse the loaders + aggregator from roll-loop-status.py. importlib because the
+# filename has a hyphen and isn't import-safe.
+_spec = importlib.util.spec_from_file_location(
+    "_rls", os.path.join(_LIB_DIR, "roll-loop-status.py")
+)
+rls = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(rls)
+
+
+def collect_cycles(days: int) -> List[Dict[str, Any]]:
+    slug = rls.project_slug()
+    events = rls.load_events(slug, days)
+    cron = rls.load_cron_log(slug)
+    runs = rls.load_runs(slug)
+    git_merges = rls.load_pr_merges_from_git(days)
+    cycles = rls.aggregate(events, cron)
+    if runs:
+        rls.merge_runs_into_cycles(cycles, runs)
+    if git_merges:
+        rls.repair_orphan_cycles_from_git(cycles, git_merges)
+    rls.backfill_usage_from_claude_sessions(cycles, slug)
+    return cycles
+
+
+def _outcome_glyph(o: str) -> str:
+    return {"fail": "✗", "running": "⏵", "idle": "·"}.get(o, "✓")
+
+
+def _fmt_dt(dt: datetime) -> str:
+    return dt.astimezone().strftime("%Y-%m-%d %H:%M")
+
+
+def _fmt_dur(s: int) -> str:
+    if not s:
+        return "—"
+    h, rem = divmod(s, 3600)
+    m, _ = divmod(rem, 60)
+    return f"{h}h {m:02d}m" if h else f"{m}m"
+
+
+def _fmt_tokens(n: int) -> str:
+    if not n:
+        return "0"
+    if n >= 1_000_000:
+        return f"{n/1_000_000:.1f}M"
+    if n >= 1_000:
+        return f"{n/1_000:.0f}k"
+    return str(n)
+
+
+def _fmt_pr(p: Dict[str, Any]) -> str:
+    g = {"merged": "✓", "closed": "✗"}.get(p["outcome"], "⏵")
+    return f"#{p['num']} {g}"
+
+
+def render_panel(r: Dict[str, Any], description: str = "") -> str:
+    head = f"── {r['story_id']}"
+    if description:
+        head += f" · {description}"
+    head += " " + "─" * max(0, 78 - len(head))
+
+    cycles = r["cycles"]
+    span = "—"
+    if r.get("span_start") and r.get("span_end"):
+        span = f"{_fmt_dt(r['span_start'])}  →  {_fmt_dt(r['span_end'])}"
+    elif r.get("span_start"):
+        span = f"{_fmt_dt(r['span_start'])}  →  (running)"
+
+    counts = f"  cycles    {r['count']}  (✓ {r['ok_count']}  ✗ {r['fail_count']}  ⏵ {r['running_count']})"
+    line_span = f"  span      {span}"
+    line_dur = (f"  duration  {_fmt_dur(r['duration_s'])}"
+                f"   tokens  in {_fmt_tokens(r['input_tokens'])}"
+                f"  out {_fmt_tokens(r['output_tokens'])}"
+                f"  cache w {_fmt_tokens(r['cache_creation_tokens'])}"
+                f"  r {_fmt_tokens(r['cache_read_tokens'])}")
+    model = r.get("model") or "—"
+    line_cost = f"  cost      ${r['cost']:.2f}    model  {model}"
+
+    prs = r.get("prs") or []
+    line_prs = "  PRs       " + (" ".join(_fmt_pr(p) for p in prs[:8]) if prs else "—")
+
+    # Recent 3 cycles (oldest → newest of the matched set; mirror confirmed layout).
+    recent = sorted(cycles, key=lambda c: c.get("start") or datetime.min.replace(tzinfo=timezone.utc))[-3:]
+    recent_lines: List[str] = []
+    for i, cy in enumerate(recent):
+        label = cy.get("label", "—")
+        glyph = _outcome_glyph(cy.get("outcome", ""))
+        cost = cy.get("cost_list")
+        cost_s = f"${cost:.2f}" if cost is not None else "—"
+        prefix = "  recent   " if i == 0 else "           "
+        recent_lines.append(f"{prefix} {label}  {glyph}  {cost_s}")
+    if not recent_lines:
+        recent_lines.append("  recent    —")
+
+    return "\n".join([head, counts, line_span, line_dur, line_cost, line_prs] + recent_lines)
+
+
+def to_json(r: Dict[str, Any]) -> str:
+    def conv(o: Any) -> Any:
+        if isinstance(o, datetime):
+            return o.astimezone(timezone.utc).isoformat()
+        raise TypeError(f"{type(o)} not serializable")
+
+    payload = {k: v for k, v in r.items() if k != "cycles"}
+    payload["cycles"] = [
+        {
+            "label": cy.get("label"),
+            "start": cy.get("start"),
+            "end": cy.get("end"),
+            "outcome": cy.get("outcome"),
+            "duration_s": cy.get("duration_s"),
+            "input_tokens": cy.get("input_tokens"),
+            "output_tokens": cy.get("output_tokens"),
+            "cache_creation_tokens": cy.get("cache_creation_tokens"),
+            "cache_read_tokens": cy.get("cache_read_tokens"),
+            "cost_list": cy.get("cost_list"),
+            "model": cy.get("model"),
+            "pr_num": cy.get("pr_num"),
+            "pr_outcome": cy.get("pr_outcome"),
+        }
+        for cy in r.get("cycles", [])
+    ]
+    return json.dumps(payload, default=conv, indent=2)
+
+
+def _backlog_description(story_id: str) -> str:
+    bl = rls.load_backlog()
+    return bl.get(story_id.upper(), "")
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(
+        description="roll loop story — per-story cycle rollup")
+    p.add_argument("story_id", help="Story ID (case-insensitive, e.g. US-LOOP-004)")
+    p.add_argument("--days", type=int, default=30,
+                   help="event window in days (default 30)")
+    p.add_argument("--json", action="store_true",
+                   help="emit machine-readable JSON instead of the panel")
+    args = p.parse_args(argv)
+
+    cycles = collect_cycles(args.days)
+    r = rls.rollup_for_story(cycles, args.story_id)
+
+    if args.json:
+        print(to_json(r))
+        return 0 if r["count"] > 0 else 2
+
+    if r["count"] == 0:
+        sys.stderr.write(
+            f"roll loop story: no cycles found for {args.story_id} "
+            f"in the last {args.days} days\n"
+            f"未找到 {args.story_id} 在最近 {args.days} 天内的循环\n"
+        )
+        return 2
+
+    print(render_panel(r, _backlog_description(args.story_id.upper())))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except BrokenPipeError:
+        pass

package/lib/roll-onboard-render.py

@@ -0,0 +1,378 @@
+#!/usr/bin/env python3
+"""
+US-ONBOARD-017: render the three Phase 2 analysis sections of onboard-plan.yaml
+(domain_model / tech_analysis / test_assessment, produced by US-ONBOARD-016)
+into human-readable markdown inside the onboarded project, and surface the
+BACKLOG / FIX seed candidates for bash to gate behind a [Y/n] confirm.
+
+This script NEVER writes to BACKLOG and NEVER touches the offboard changeset.
+Those mutations stay in bash (bin/roll `_init_apply`) so the confirm gate and
+the rollback registry remain the single source of truth. This script only:
+
+  1. Renders three markdown files into <project_dir>/.roll/ , deterministically
+     (same plan.yaml -> byte-identical markdown; no wall-clock timestamps or
+     random IDs are embedded in the body).
+  2. Emits a machine-parseable manifest on stdout describing exactly what it
+     wrote and what could be seeded, in a pipe-delimited line format that bash
+     parses with `IFS='|' read` (no jq dependency):
+
+        FILE|.roll/domain/context-map.md
+        FILE|.roll/tech-analysis.md
+        FILE|.roll/test-assessment.md
+        SEED|US-SEED-001|add a macOS CI runner
+        FIX|FIX-SEED-001|no automated test run on macOS bash 3.2
+
+     `FILE|` lines are project-relative paths bash records into the changeset's
+     `files_created` (so `roll offboard` removes them). `SEED|` / `FIX|` lines
+     are candidates; bash prints a preview and only writes them on explicit
+     confirmation.
+
+Atomicity (per peer review): all three files are staged to temp paths inside
+the project dir and atomically renamed into place. If rendering any file fails,
+nothing is left half-written and no manifest is emitted, so bash records no
+changeset entries for files that do not exist.
+
+Usage:
+    python3 roll-onboard-render.py <plan.yaml> <project_dir>
+
+Exit codes:
+    0   rendered OK (manifest on stdout)
+    1   plan unreadable / not a mapping / render failure
+    2   plan has none of the three sections (nothing to render; no-op)
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+try:
+    import yaml  # PyYAML
+except ImportError:
+    print(
+        "[onboard-render] PyYAML not installed. Install with: pip install pyyaml\n"
+        "[onboard-render] PyYAML 未安装，请运行: pip install pyyaml",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+
+# Project-relative output paths (the AC fixes these three exact locations).
+CONTEXT_MAP_REL = ".roll/domain/context-map.md"
+TECH_ANALYSIS_REL = ".roll/tech-analysis.md"
+TEST_ASSESSMENT_REL = ".roll/test-assessment.md"
+
+# HIGH-severity risks are the only ones eligible to seed as FIX candidates.
+HIGH_SEVERITY = "HIGH"
+
+
+def _as_list(value) -> list:
+    """Coerce a possibly-missing field into a list, preserving order.
+
+    A scalar becomes a one-item list; None/missing becomes []. Never sorts —
+    determinism comes from honouring the author's order in the plan.
+    """
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    return [value]
+
+
+def _term_text(term) -> str:
+    """Render a ubiquitous_language entry, which may be a bare string or a
+    {term, definition} mapping (the schema allows both)."""
+    if isinstance(term, dict):
+        name = str(term.get("term", "")).strip()
+        definition = str(term.get("definition", "")).strip()
+        if name and definition:
+            return f"{name} — {definition}"
+        return name or definition
+    return str(term).strip()
+
+
+def _claim_text(claim) -> tuple[str, str]:
+    """Return (text, evidence) for a test_assessment claim.
+
+    Claims are validated upstream as mappings carrying an `evidence` tag, but we
+    stay defensive so a malformed-but-parseable plan still renders rather than
+    crashing.
+    """
+    if isinstance(claim, dict):
+        text = str(claim.get("claim", "")).strip()
+        evidence = str(claim.get("evidence", "")).strip()
+        return text, evidence
+    return str(claim).strip(), ""
+
+
+def render_context_map(domain_model: dict | None) -> str:
+    """Render .roll/domain/context-map.md from domain_model. Deterministic."""
+    lines: list[str] = ["# Domain Context Map", ""]
+    lines.append(
+        "> Generated by `roll init --apply` from `.roll/onboard-plan.yaml` "
+        "(US-ONBOARD-016/017). Regenerate by re-running onboard."
+    )
+    lines.append("")
+    contexts = _as_list((domain_model or {}).get("bounded_contexts"))
+    if not contexts:
+        lines.append("_No bounded contexts were inferred from the codebase._")
+        lines.append("")
+        return "\n".join(lines) + "\n"
+
+    for ctx in contexts:
+        if not isinstance(ctx, dict):
+            continue
+        name = str(ctx.get("name", "")).strip() or "(unnamed context)"
+        lines.append(f"## {name}")
+        lines.append("")
+        aggregates = _as_list(ctx.get("aggregates"))
+        lines.append("**Aggregates**")
+        lines.append("")
+        if aggregates:
+            for agg in aggregates:
+                lines.append(f"- {str(agg).strip()}")
+        else:
+            lines.append("- _none identified_")
+        lines.append("")
+        language = _as_list(ctx.get("ubiquitous_language"))
+        lines.append("**Ubiquitous language**")
+        lines.append("")
+        if language:
+            for term in language:
+                text = _term_text(term)
+                if text:
+                    lines.append(f"- {text}")
+        else:
+            lines.append("- _none identified_")
+        lines.append("")
+    return "\n".join(lines) + "\n"
+
+
+def render_tech_analysis(tech: dict | None) -> str:
+    """Render .roll/tech-analysis.md from tech_analysis. Deterministic."""
+    lines: list[str] = ["# Technical Analysis", ""]
+    lines.append(
+        "> Generated by `roll init --apply` from `.roll/onboard-plan.yaml` "
+        "(US-ONBOARD-016/017). Regenerate by re-running onboard."
+    )
+    lines.append("")
+    tech = tech or {}
+
+    def _bullet_section(title: str, key: str) -> None:
+        lines.append(f"## {title}")
+        lines.append("")
+        items = _as_list(tech.get(key))
+        if items:
+            for item in items:
+                lines.append(f"- {str(item).strip()}")
+        else:
+            lines.append("- _none detected_")
+        lines.append("")
+
+    _bullet_section("Stack", "stack")
+    _bullet_section("Dependencies", "dependencies")
+    _bullet_section("Architecture notes", "architecture_notes")
+
+    lines.append("## Risks")
+    lines.append("")
+    risks = _as_list(tech.get("risks"))
+    if not risks:
+        lines.append("- _none detected_")
+        lines.append("")
+        return "\n".join(lines) + "\n"
+
+    for risk in risks:
+        if not isinstance(risk, dict):
+            lines.append(f"- {str(risk).strip()}")
+            continue
+        desc = str(risk.get("description", "")).strip()
+        severity = str(risk.get("severity", "")).strip()
+        evidence = str(risk.get("evidence", "")).strip()
+        tags = []
+        if severity:
+            tags.append(f"severity: {severity}")
+        if evidence:
+            tags.append(f"evidence: {evidence}")
+        suffix = f" ({', '.join(tags)})" if tags else ""
+        lines.append(f"- {desc}{suffix}")
+    lines.append("")
+    return "\n".join(lines) + "\n"
+
+
+def render_test_assessment(test: dict | None) -> str:
+    """Render .roll/test-assessment.md from test_assessment. Deterministic.
+
+    Distinguishes `detected` (a real scan finding) from `inferred` (a judgement)
+    by labelling each bullet, honouring US-ONBOARD-016's evidence contract.
+    """
+    lines: list[str] = ["# Test Coverage Assessment", ""]
+    lines.append(
+        "> Generated by `roll init --apply` from `.roll/onboard-plan.yaml` "
+        "(US-ONBOARD-016/017). Every claim is evidence-tagged: **detected** "
+        "(found by a filesystem scan) or **inferred** (a judgement traceable to "
+        "a detected fact)."
+    )
+    lines.append("")
+    test = test or {}
+
+    def _claims_section(title: str, key: str) -> None:
+        lines.append(f"## {title}")
+        lines.append("")
+        claims = _as_list(test.get(key))
+        if claims:
+            for claim in claims:
+                text, evidence = _claim_text(claim)
+                if not text:
+                    continue
+                if evidence:
+                    lines.append(f"- {text} _(evidence: {evidence})_")
+                else:
+                    lines.append(f"- {text}")
+        else:
+            lines.append("- _none recorded_")
+        lines.append("")
+
+    _claims_section("Current layers", "current_layers")
+    _claims_section("Gaps", "gaps")
+    _claims_section("Recommended actions", "recommended_actions")
+    return "\n".join(lines) + "\n"
+
+
+def collect_seed_candidates(plan: dict) -> tuple[list[str], list[str]]:
+    """Return (story_titles, fix_titles) in plan order.
+
+    Stories come from test_assessment.recommended_actions (each becomes a
+    candidate BACKLOG story). FIX candidates come from tech_analysis.risks whose
+    severity == HIGH. Titles are the human-readable claim/description text;
+    bash assigns the deterministic US-SEED-NNN / FIX-SEED-NNN ids.
+    """
+    stories: list[str] = []
+    test = plan.get("test_assessment") or {}
+    for claim in _as_list(test.get("recommended_actions")):
+        text, _ = _claim_text(claim)
+        if text and text.lower() != "none detected":
+            stories.append(text)
+
+    fixes: list[str] = []
+    tech = plan.get("tech_analysis") or {}
+    for risk in _as_list(tech.get("risks")):
+        if not isinstance(risk, dict):
+            continue
+        if str(risk.get("severity", "")).strip().upper() == HIGH_SEVERITY:
+            desc = str(risk.get("description", "")).strip()
+            if desc:
+                fixes.append(desc)
+    return stories, fixes
+
+
+def _atomic_write(project_dir: Path, rel: str, content: str) -> None:
+    """Write content to <project_dir>/<rel> atomically (temp + os.replace).
+
+    The temp file is created in the same directory as the target so the rename
+    is atomic on the same filesystem.
+    """
+    target = project_dir / rel
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=f".{target.name}.", suffix=".tmp", dir=str(target.parent)
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(content)
+        os.replace(tmp_name, str(target))
+    except BaseException:
+        # Clean up the temp file on any failure so we never leak half-writes.
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+
+
+def _emit(line: str) -> None:
+    sys.stdout.write(line + "\n")
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 3:
+        print(
+            "[onboard-render] usage: roll-onboard-render.py <plan.yaml> <project_dir>",
+            file=sys.stderr,
+        )
+        return 1
+
+    plan_path = Path(argv[1])
+    project_dir = Path(argv[2])
+
+    if not plan_path.is_file():
+        print(f"[onboard-render] plan not found: {plan_path}", file=sys.stderr)
+        return 1
+    if not project_dir.is_dir():
+        print(
+            f"[onboard-render] project dir not found: {project_dir}", file=sys.stderr
+        )
+        return 1
+
+    try:
+        with plan_path.open("r", encoding="utf-8") as f:
+            plan = yaml.safe_load(f)
+    except (yaml.YAMLError, OSError) as e:
+        print(f"[onboard-render] failed to parse plan: {e}", file=sys.stderr)
+        return 1
+
+    if not isinstance(plan, dict):
+        print("[onboard-render] plan must be a top-level mapping", file=sys.stderr)
+        return 1
+
+    has_dm = isinstance(plan.get("domain_model"), dict)
+    has_ta = isinstance(plan.get("tech_analysis"), dict)
+    has_test = isinstance(plan.get("test_assessment"), dict)
+    if not (has_dm or has_ta or has_test):
+        # No Phase 2 content at all — nothing to render. Bash treats exit 2 as a
+        # clean no-op (an old plan, or a minimal onboard).
+        return 2
+
+    # Render bodies first (pure, in-memory) so a render bug fails before we
+    # touch the filesystem at all.
+    try:
+        bodies = [
+            (CONTEXT_MAP_REL, render_context_map(plan.get("domain_model"))),
+            (TECH_ANALYSIS_REL, render_tech_analysis(plan.get("tech_analysis"))),
+            (TEST_ASSESSMENT_REL, render_test_assessment(plan.get("test_assessment"))),
+        ]
+    except Exception as e:  # pragma: no cover - defensive
+        print(f"[onboard-render] render failed: {e}", file=sys.stderr)
+        return 1
+
+    # Stage + atomically write all three. If any write fails, roll back the
+    # ones already renamed so we never leave partial state.
+    written: list[str] = []
+    try:
+        for rel, body in bodies:
+            _atomic_write(project_dir, rel, body)
+            written.append(rel)
+    except OSError as e:
+        for rel in written:
+            try:
+                os.unlink(str(project_dir / rel))
+            except OSError:
+                pass
+        print(f"[onboard-render] write failed: {e}", file=sys.stderr)
+        return 1
+
+    stories, fixes = collect_seed_candidates(plan)
+
+    # Emit the manifest only after every file is on disk.
+    for rel, _ in bodies:
+        _emit(f"FILE|{rel}")
+    for i, title in enumerate(stories, start=1):
+        _emit(f"SEED|US-SEED-{i:03d}|{title}")
+    for i, desc in enumerate(fixes, start=1):
+        _emit(f"FIX|FIX-SEED-{i:03d}|{desc}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))