ma-agents 3.13.2 → 3.14.0

package/lib/bmad-cache/bmb/skills/bmad-workflow-builder/scripts/render_report.py

@@ -0,0 +1,387 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""Render the analysis report deterministically from findings JSON.
+
+Injects a validated findings JSON object into the report shell's
+report-data island and writes the self-contained HTML atomically.
+With --md, also writes a markdown rendering of the same data as the
+archival artifact.
+
+Refuses (non-zero exit, message on stderr) when the JSON does not
+parse, fails shape validation, or still carries the shell's
+placeholder subject — a refused render means fix the findings file
+and re-run, never hand-edit the HTML.
+
+Usage:
+  uv run render_report.py <findings.json> --shell <report-shell.html> \
+      -o <out.html> [--md <out.md>]
+
+On success prints one JSON line: output paths, grade, and severity
+counts derived from the findings array.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import tempfile
+from pathlib import Path
+
+SEVERITIES = ("critical", "high", "medium", "low")
+GRADES = ("excellent", "good", "fair", "poor")
+PLACEHOLDER_SUBJECT = "__PLACEHOLDER__"
+ISLAND_RE = re.compile(
+    r'(<script[^>]*\bid="report-data"[^>]*>)(.*?)(</script>)', re.DOTALL
+)
+
+
+def fail(message: str) -> None:
+    print(f"render_report: {message}", file=sys.stderr)
+    sys.exit(1)
+
+
+def validate(data: object) -> list[str]:
+    """Return a list of shape errors; empty list means valid."""
+    if not isinstance(data, dict):
+        return ["top level must be a JSON object"]
+    errors: list[str] = []
+
+    subject = data.get("subject")
+    if not isinstance(subject, str) or not subject.strip():
+        errors.append('"subject" must be a non-empty string')
+    elif PLACEHOLDER_SUBJECT in subject:
+        errors.append(
+            f'"subject" still carries the placeholder {PLACEHOLDER_SUBJECT}; '
+            "this is the unfilled shell sample, not real findings"
+        )
+
+    findings = data.get("findings")
+    if not isinstance(findings, list):
+        errors.append('"findings" must be an array (use [] for a clean pass)')
+    else:
+        for i, finding in enumerate(findings):
+            if not isinstance(finding, dict):
+                errors.append(f"findings[{i}] must be an object")
+
+    grade = data.get("grade")
+    if grade is not None and grade not in GRADES:
+        errors.append(f'"grade" must be one of: {", ".join(GRADES)}')
+
+    for key in ("themes", "recommendations"):
+        value = data.get(key)
+        if value is not None and (
+            not isinstance(value, list)
+            or any(not isinstance(item, dict) for item in value)
+        ):
+            errors.append(f'"{key}" must be an array of objects')
+
+    strengths = data.get("strengths")
+    if strengths is not None and (
+        not isinstance(strengths, list)
+        or any(not isinstance(item, str) for item in strengths)
+    ):
+        errors.append('"strengths" must be an array of strings')
+
+    return errors
+
+
+def severity_counts(findings: list[dict]) -> dict[str, int]:
+    counts = {sev: 0 for sev in SEVERITIES}
+    for finding in findings:
+        sev = finding.get("severity")
+        counts[sev if sev in counts else "low"] += 1
+    return counts
+
+
+def inject(shell_html: str, data: dict) -> str:
+    payload = json.dumps(data, ensure_ascii=False, indent=2)
+    # A "</" sequence inside a JSON string would close the script tag
+    # early in the browser; "<\/" is the same string to JSON.parse.
+    payload = payload.replace("</", "<\\/")
+
+    def replace(match: re.Match) -> str:
+        return match.group(1) + "\n" + payload + "\n" + match.group(3)
+
+    new_html, count = ISLAND_RE.subn(replace, shell_html, count=1)
+    if count != 1:
+        fail('shell has no <script id="report-data"> island to fill')
+    return new_html
+
+
+def atomic_write(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(
+        dir=path.parent, prefix=path.name + ".", suffix=".tmp"
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _finding_lines(finding: dict, heading_level: str) -> list[str]:
+    fid = str(finding.get("id", ""))
+    title = str(finding.get("title", "(untitled finding)"))
+    lines = [f"{heading_level} {fid} — {title}" if fid else f"{heading_level} {title}", ""]
+    for key, label in (
+        ("lens", "Lens"),
+        ("location", "Location"),
+        ("evidence", "Evidence"),
+        ("recommendation", "Recommendation"),
+        ("proposed_smallest", "Proposed smallest"),
+        ("predicted_delta", "Predicted delta"),
+    ):
+        value = finding.get(key)
+        if value:
+            value = f"`{value}`" if key == "location" else str(value)
+            lines.append(f"- {label}: {value}")
+    lines.append("")
+    return lines
+
+
+def render_md(data: dict) -> str:
+    findings = [f for f in data.get("findings", []) if isinstance(f, dict)]
+    by_id = {str(f.get("id")): f for f in findings if f.get("id") is not None}
+    counts = severity_counts(findings)
+    lines: list[str] = []
+
+    lines.append(f"# Analysis Report: {data.get('subject', '')}")
+    lines.append("")
+    meta = []
+    if data.get("generated"):
+        meta.append(f"Generated: {data['generated']}")
+    if data.get("schema_version") is not None:
+        meta.append(f"Schema: {data['schema_version']}")
+    if meta:
+        lines.append(" · ".join(meta))
+        lines.append("")
+
+    if data.get("grade"):
+        lines.append(f"**Grade: {str(data['grade']).capitalize()}**")
+        lines.append("")
+    if data.get("verdict"):
+        lines.append(f"> {data['verdict']}")
+        lines.append("")
+    summary = data.get("summary")
+    if isinstance(summary, str) and summary:
+        lines.append(summary)
+        lines.append("")
+
+    lines.append("| Severity | Count |")
+    lines.append("| --- | --- |")
+    for sev in SEVERITIES:
+        lines.append(f"| {sev.capitalize()} | {counts[sev]} |")
+    lines.append("")
+
+    themes = data.get("themes") or []
+    if themes:
+        lines.append("## Themes")
+        lines.append("")
+        for i, theme in enumerate(themes, 1):
+            lines.append(f"### {i}. {theme.get('title', '(untitled theme)')}")
+            lines.append("")
+            if theme.get("root_cause"):
+                lines.append(f"- Root cause: {theme['root_cause']}")
+            if theme.get("action"):
+                lines.append(f"- Fix: {theme['action']}")
+            ids = theme.get("finding_ids") or []
+            if ids:
+                lines.append("- Findings:")
+                for fid in ids:
+                    finding = by_id.get(str(fid))
+                    if finding:
+                        loc = finding.get("location")
+                        suffix = f" — `{loc}`" if loc else ""
+                        lines.append(
+                            f"  - `{fid}` {finding.get('title', '')}{suffix}"
+                        )
+                    else:
+                        lines.append(f"  - `{fid}`")
+            lines.append("")
+
+    strengths = data.get("strengths") or []
+    if strengths:
+        lines.append("## Strengths")
+        lines.append("")
+        for strength in strengths:
+            lines.append(f"- {strength}")
+        lines.append("")
+
+    recommendations = data.get("recommendations") or []
+    if recommendations:
+        lines.append("## Recommendations")
+        lines.append("")
+        for i, rec in enumerate(recommendations, 1):
+            rank = rec.get("rank", i)
+            resolves = rec.get("resolves")
+            if isinstance(resolves, list) and resolves:
+                suffix = " (resolves: " + ", ".join(map(str, resolves)) + ")"
+            elif isinstance(resolves, (int, float)):
+                suffix = f" (resolves {int(resolves)} findings)"
+            else:
+                suffix = ""
+            lines.append(f"{rank}. {rec.get('action', '')}{suffix}")
+        lines.append("")
+
+    # Optional agent blocks: rendered only when present so the same
+    # renderer serves both the workflow and agent schemas.
+    profile = data.get("agent_profile")
+    if isinstance(profile, dict) and any(profile.values()):
+        lines.append("## Agent Profile")
+        lines.append("")
+        for key, label in (
+            ("name", "Name"),
+            ("title", "Title"),
+            ("agent_type", "Type"),
+            ("mission", "Mission"),
+        ):
+            if profile.get(key):
+                lines.append(f"- {label}: {profile[key]}")
+        lines.append("")
+
+    capabilities = data.get("capabilities")
+    if isinstance(capabilities, list) and capabilities:
+        lines.append("## Capabilities")
+        lines.append("")
+        for cap in capabilities:
+            if not isinstance(cap, dict) or not cap.get("name"):
+                continue
+            kind = f" ({cap['kind']})" if cap.get("kind") else ""
+            note = f" — {cap['note']}" if cap.get("note") else ""
+            lines.append(f"- **{cap['name']}**{kind}{note}")
+        lines.append("")
+
+    detailed = data.get("detailed_analysis")
+    if isinstance(detailed, dict) and detailed:
+        lines.append("## Per-Lens Verdicts")
+        lines.append("")
+        for lens, verdict in detailed.items():
+            if verdict:
+                lines.append(f"- **{lens}**: {verdict}")
+        lines.append("")
+
+    sanctum = data.get("sanctum")
+    if isinstance(sanctum, dict) and sanctum.get("present") is not False:
+        rows = []
+        if sanctum.get("location"):
+            rows.append(f"- Location: `{sanctum['location']}`")
+        files = sanctum.get("files") or []
+        if files:
+            rows.append("- Files: " + ", ".join(f"`{f}`" for f in files))
+        if sanctum.get("note"):
+            rows.append(f"- Note: {sanctum['note']}")
+        if rows:
+            lines.append("## Sanctum (runtime memory)")
+            lines.append("")
+            lines.extend(rows)
+            lines.append("")
+
+    experience = data.get("experience")
+    if isinstance(experience, dict):
+        journeys = [
+            j for j in experience.get("journeys") or [] if isinstance(j, dict)
+        ]
+        headless = experience.get("headless")
+        if journeys or headless:
+            lines.append("## Experience")
+            lines.append("")
+            for journey in journeys:
+                steps = f" — {journey['steps']}" if journey.get("steps") else ""
+                lines.append(f"- **{journey.get('name', '(unnamed journey)')}**{steps}")
+            if headless:
+                lines.append(f"- Headless: {headless}")
+            lines.append("")
+
+    lines.append("## Findings")
+    lines.append("")
+    if not findings:
+        lines.append("No findings: the scanners returned a clean pass.")
+        lines.append("")
+    else:
+        for sev in SEVERITIES:
+            group = [
+                f
+                for f in findings
+                if (f.get("severity") if f.get("severity") in SEVERITIES else "low")
+                == sev
+            ]
+            if not group:
+                continue
+            lines.append(f"### {sev.capitalize()} ({len(group)})")
+            lines.append("")
+            for finding in group:
+                lines.extend(_finding_lines(finding, "####"))
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Inject findings JSON into the report shell and render HTML (+ optional markdown)."
+    )
+    parser.add_argument("findings", type=Path, help="path to findings.json")
+    parser.add_argument(
+        "--shell", type=Path, required=True, help="path to report-shell.html"
+    )
+    parser.add_argument(
+        "-o", "--output", type=Path, required=True, help="output HTML path"
+    )
+    parser.add_argument(
+        "--md", type=Path, help="also write a markdown rendering to this path"
+    )
+    args = parser.parse_args()
+
+    try:
+        raw = args.findings.read_text(encoding="utf-8")
+    except OSError as err:
+        fail(f"cannot read {args.findings}: {err}")
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as err:
+        fail(f"{args.findings} is not valid JSON: {err}")
+
+    errors = validate(data)
+    if errors:
+        fail(
+            f"{args.findings} failed shape validation:\n  - "
+            + "\n  - ".join(errors)
+        )
+
+    try:
+        shell_html = args.shell.read_text(encoding="utf-8")
+    except OSError as err:
+        fail(f"cannot read shell {args.shell}: {err}")
+
+    atomic_write(args.output, inject(shell_html, data))
+    if args.md:
+        atomic_write(args.md, render_md(data))
+
+    findings = [f for f in data.get("findings", []) if isinstance(f, dict)]
+    print(
+        json.dumps(
+            {
+                "html_report": str(args.output),
+                "md_report": str(args.md) if args.md else None,
+                "grade": data.get("grade"),
+                "counts": severity_counts(findings),
+                "findings": len(findings),
+            }
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/lib/bmad-cache/bmb/skills/bmad-workflow-builder/scripts/tests/test_canon_sync.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Guard against drift between the embedded prompt-quality-canon copies.
+
+The canon is embedded in three places — workflow-builder references,
+agent-builder references, and the agent-builder asset emitted into built
+agents — with no in-file sync note, because the loaded files are LLM-facing
+and a maintenance comment there is paid on every load. This test is the
+sync mechanism instead: all three copies must be byte-identical.
+Run with: python3 -m pytest test_canon_sync.py
+(or plain `python3 test_canon_sync.py` for a lightweight self-check).
+"""
+import sys
+from pathlib import Path
+
+SKILLS_DIR = Path(__file__).resolve().parents[3]
+
+CANON_COPIES = [
+    SKILLS_DIR / "bmad-workflow-builder" / "references" / "prompt-quality-canon.md",
+    SKILLS_DIR / "bmad-agent-builder" / "references" / "prompt-quality-canon.md",
+    SKILLS_DIR / "bmad-agent-builder" / "assets" / "prompt-quality-canon.md",
+]
+
+
+def test_all_copies_exist():
+    missing = [str(p) for p in CANON_COPIES if not p.is_file()]
+    assert not missing, f"canon copy missing: {missing}"
+
+
+def test_all_copies_identical():
+    contents = {p: p.read_bytes() for p in CANON_COPIES if p.is_file()}
+    reference = CANON_COPIES[0]
+    diverged = [
+        str(p)
+        for p, body in contents.items()
+        if body != contents.get(reference)
+    ]
+    assert not diverged, (
+        "canon copies have drifted from "
+        f"{reference}: {diverged} — sync all copies together"
+    )
+
+
+if __name__ == "__main__":
+    test_all_copies_exist()
+    test_all_copies_identical()
+    print(f"ok: {len(CANON_COPIES)} canon copies present and identical")

package/lib/bmad-cache/bmb/skills/bmad-workflow-builder/scripts/tests/test_count_tokens.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""Tests for count_tokens.py.
+
+Covers the output schema, the tiktoken path and the forced-fallback path
+agreeing within tolerance, the CLI over a file and over stdin, and argument
+guards. Run with: python3 -m pytest test_count_tokens.py
+(or plain `python3 test_count_tokens.py` to run a lightweight self-check).
+"""
+import builtins
+import importlib.util
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+SCRIPT = Path(__file__).resolve().parent.parent / "count_tokens.py"
+
+SAMPLE = (
+    "The builder is platform-agnostic. Nothing assumes a single runtime, and no "
+    "model list is ever hardcoded. Token counts replace line counts as the one "
+    "length metric, with a chars-over-four fallback when tiktoken is absent.\n"
+) * 8
+
+
+def _load_module():
+    spec = importlib.util.spec_from_file_location("count_tokens", SCRIPT)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def test_tiktoken_path():
+    mod = _load_module()
+    try:
+        import tiktoken  # noqa: F401
+    except Exception:
+        # No tiktoken in this interpreter; the real path can't be exercised here.
+        tokens, method = mod.count_tokens(SAMPLE)
+        assert method == "fallback"
+        assert tokens == len(SAMPLE) // 4
+        return
+    tokens, method = mod.count_tokens(SAMPLE)
+    assert method == "tiktoken"
+    assert isinstance(tokens, int)
+    assert tokens > 0
+
+
+def test_fallback_path_when_import_blocked():
+    """Force the import of tiktoken to fail and confirm the fallback fires."""
+    mod = _load_module()
+    real_import = builtins.__import__
+
+    def blocked_import(name, *args, **kwargs):
+        if name == "tiktoken" or name.startswith("tiktoken."):
+            raise ImportError("blocked for test")
+        return real_import(name, *args, **kwargs)
+
+    builtins.__import__ = blocked_import
+    try:
+        tokens, method = mod.count_tokens(SAMPLE)
+    finally:
+        builtins.__import__ = real_import
+
+    assert method == "fallback"
+    assert tokens == len(SAMPLE) // 4
+
+
+def test_paths_agree_within_tolerance():
+    """tiktoken and chars//4 should be in the same order of magnitude.
+
+    Skipped when tiktoken is not installed (nothing to compare against).
+    """
+    mod = _load_module()
+    try:
+        import tiktoken  # noqa: F401
+    except Exception:
+        return
+
+    real_tokens, real_method = mod.count_tokens(SAMPLE)
+    assert real_method == "tiktoken"
+
+    fallback_tokens = len(SAMPLE) // 4
+
+    # The chars//4 heuristic is a rough proxy; require it within +/-50% of the
+    # real count so the fallback stays a usable budget gate, not a wild guess.
+    lower = real_tokens * 0.5
+    upper = real_tokens * 1.5
+    assert lower <= fallback_tokens <= upper, (
+        f"fallback {fallback_tokens} not within 50% of tiktoken {real_tokens}"
+    )
+
+
+def test_cli_file_output_schema(tmp_path):
+    f = tmp_path / "sample.md"
+    f.write_text(SAMPLE, encoding="utf-8")
+    out = subprocess.run(
+        [sys.executable, str(SCRIPT), str(f)],
+        capture_output=True, text=True, check=True,
+    ).stdout
+    data = json.loads(out)
+    assert set(data.keys()) == {"tokens", "method"}
+    assert isinstance(data["tokens"], int)
+    assert data["method"] in ("tiktoken", "fallback")
+    assert data["tokens"] > 0
+
+
+def test_cli_stdin_output_schema():
+    out = subprocess.run(
+        [sys.executable, str(SCRIPT), "--stdin"],
+        input=SAMPLE, capture_output=True, text=True, check=True,
+    ).stdout
+    data = json.loads(out)
+    assert set(data.keys()) == {"tokens", "method"}
+    assert isinstance(data["tokens"], int)
+    assert data["method"] in ("tiktoken", "fallback")
+
+
+def test_cli_file_and_stdin_agree():
+    """The CLI over a file and over stdin produce the same count for same text."""
+    import tempfile, os
+    fd, name = tempfile.mkstemp(suffix=".md")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(SAMPLE)
+        file_out = json.loads(subprocess.run(
+            [sys.executable, str(SCRIPT), name],
+            capture_output=True, text=True, check=True,
+        ).stdout)
+    finally:
+        os.unlink(name)
+    stdin_out = json.loads(subprocess.run(
+        [sys.executable, str(SCRIPT), "--stdin"],
+        input=SAMPLE, capture_output=True, text=True, check=True,
+    ).stdout)
+    assert file_out == stdin_out
+
+
+def test_cli_requires_an_input():
+    """No file and no --stdin is a usage error (exit 2 from argparse)."""
+    res = subprocess.run(
+        [sys.executable, str(SCRIPT)],
+        capture_output=True, text=True,
+    )
+    assert res.returncode != 0
+
+
+def _run_all():
+    import tempfile
+    failures = 0
+    tests = [
+        test_tiktoken_path,
+        test_fallback_path_when_import_blocked,
+        test_paths_agree_within_tolerance,
+        test_cli_stdin_output_schema,
+        test_cli_file_and_stdin_agree,
+        test_cli_requires_an_input,
+    ]
+    for t in tests:
+        try:
+            t()
+            print(f"PASS {t.__name__}")
+        except AssertionError as e:
+            failures += 1
+            print(f"FAIL {t.__name__}: {e}")
+        except Exception as e:
+            failures += 1
+            print(f"ERROR {t.__name__}: {e}")
+    # tmp_path-based test handled separately
+    with tempfile.TemporaryDirectory() as d:
+        try:
+            test_cli_file_output_schema(Path(d))
+            print("PASS test_cli_file_output_schema")
+        except Exception as e:
+            failures += 1
+            print(f"FAIL test_cli_file_output_schema: {e}")
+    return failures
+
+
+if __name__ == "__main__":
+    sys.exit(1 if _run_all() else 0)