prizmkit 1.1.125 → 1.1.127

package/bundled/skills/prizmkit-code-review/scripts/render_review_report.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Render the final review-report.md from minimal review data."""
+"""Initialize and append validated sections to review-report.md."""
 
 from __future__ import annotations
 
@@ -10,153 +10,285 @@ from pathlib import Path
 from typing import Any
 
 VERDICTS = {"PASS", "NEEDS_FIXES", "BLOCKED"}
-DISPOSITIONS = ("fixed", "rejected", "unresolved")
+RISKS = {"low", "medium", "high"}
+EVENTS = {
+    "risk-assessment",
+    "main-review-round",
+    "repair-verification",
+    "reviewer-running",
+    "reviewer-result",
+    "infrastructure-failure",
+    "final-verification",
+}
+FINAL_HEADING = "## Final Result"
 
 
 class ReportStateError(ValueError):
-    """Raised when review data cannot produce a valid final report."""
+    """Raised when an operation would produce an invalid report lifecycle."""
 
 
-def _require_count(data: dict[str, Any], name: str) -> int:
+def _require_object(data: Any) -> dict[str, Any]:
+    if not isinstance(data, dict):
+        raise ReportStateError("input must be a JSON object")
+    return data
+
+
+def _require_text(data: dict[str, Any], name: str) -> str:
+    value = data.get(name)
+    if not isinstance(value, str) or not value.strip():
+        raise ReportStateError(f"{name} must be a non-empty string")
+    return value.strip()
+
+
+def _require_count(data: dict[str, Any], name: str, *, maximum: int | None = None) -> int:
     value = data.get(name)
     if not isinstance(value, int) or isinstance(value, bool) or value < 0:
         raise ReportStateError(f"{name} must be a non-negative integer")
+    if maximum is not None and value > maximum:
+        raise ReportStateError(f"{name} cannot exceed {maximum}")
     return value
 
 
-def validate_data(data: Any) -> dict[str, Any]:
-    if not isinstance(data, dict):
-        raise ReportStateError("review data must be a JSON object")
+def _require_risk(data: dict[str, Any]) -> str:
+    risk = data.get("risk")
+    if risk not in RISKS:
+        raise ReportStateError(f"risk has invalid value: {risk!r}")
+    return risk
+
+
+def _report_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except FileNotFoundError as error:
+        raise ReportStateError("report must be initialized before append") from error
+
+
+def _ensure_appendable(path: Path) -> None:
+    text = _report_text(path)
+    if "## Status: IN_PROGRESS" not in text:
+        raise ReportStateError("report is not an initialized in-progress execution")
+    if FINAL_HEADING in text:
+        raise ReportStateError("cannot append after Final Result")
+
+
+def _append_section(path: Path, section: str) -> None:
+    with path.open("a", encoding="utf-8") as report:
+        report.write(section.rstrip() + "\n\n")
+
+
+def initialize_report(path: Path) -> None:
+    """Start a new execution and remove stale prior execution content."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("# Review Report\n\n## Status: IN_PROGRESS\n\n", encoding="utf-8")
 
-    verdict = data.get("verdict")
-    if verdict not in VERDICTS:
-        raise ReportStateError(f"verdict has invalid value: {verdict!r}")
 
-    rounds_completed = _require_count(data, "rounds_completed")
-    if rounds_completed > 10:
-        raise ReportStateError("rounds_completed cannot exceed ten")
-
-    findings = data.get("findings")
-    if not isinstance(findings, list):
-        raise ReportStateError("findings must be an array")
-
-    summary = data.get("summary")
-    if not isinstance(summary, str) or not summary.strip():
-        raise ReportStateError("summary must be a non-empty string")
-
-    for index, finding in enumerate(findings, start=1):
-        if not isinstance(finding, dict):
-            raise ReportStateError(f"finding {index} must be an object")
-        required = {
-            "title",
-            "severity",
-            "location",
-            "problem",
-            "failure_scenario",
-            "disposition",
-        }
-        missing = sorted(required - finding.keys())
-        if missing:
-            raise ReportStateError(
-                f"finding {index} missing fields: {', '.join(missing)}"
-            )
-        disposition = finding["disposition"]
-        if not isinstance(disposition, str) or not disposition.startswith(DISPOSITIONS):
-            raise ReportStateError(f"finding {index} has invalid disposition")
-
-    unresolved = sum(
-        finding["disposition"].startswith("unresolved") for finding in findings
+def _render_event(data: dict[str, Any]) -> str:
+    event = data.get("event")
+    if event not in EVENTS:
+        raise ReportStateError(f"event has invalid value: {event!r}")
+
+    if event == "risk-assessment":
+        risk = _require_risk(data)
+        reasons = data.get("reasons")
+        if not isinstance(reasons, list) or not reasons or not all(
+            isinstance(reason, str) and reason.strip() for reason in reasons
+        ):
+            raise ReportStateError("reasons must be a non-empty string array")
+        limit = {"low": 0, "medium": 1, "high": 2}[risk]
+        lines = [
+            "## Risk Assessment",
+            "",
+            f"- Risk: {risk}",
+            f"- Independent Reviewer Limit: {limit}",
+            "- Reasons:",
+        ]
+        lines.extend(f"  - {reason.strip()}" for reason in reasons)
+        return "\n".join(lines)
+
+    if event == "main-review-round":
+        round_number = _require_count(data, "round", maximum=10)
+        if round_number < 1:
+            raise ReportStateError("round must be at least 1")
+        findings = _require_count(data, "findings")
+        accepted = _require_count(data, "accepted")
+        rejected = _require_count(data, "rejected")
+        if accepted + rejected != findings:
+            raise ReportStateError("accepted + rejected must equal findings")
+        return "\n".join(
+            [
+                f"## Main Review Round {round_number}",
+                "",
+                "- Status: COMPLETED",
+                f"- Findings: {findings}",
+                f"- Accepted: {accepted}",
+                f"- Rejected: {rejected}",
+                f"- Next: {_require_text(data, 'next')}",
+            ]
+        )
+
+    if event == "repair-verification":
+        source = _require_text(data, "source")
+        if source not in {"main", "reviewer-1", "reviewer-2"}:
+            raise ReportStateError(f"source has invalid value: {source!r}")
+        return "\n".join(
+            [
+                "## Repair Verification",
+                "",
+                f"- Source: {source}",
+                f"- Fixed Findings: {_require_count(data, 'fixed_findings')}",
+                f"- Verification: {_require_text(data, 'verification')}",
+                f"- Next: {_require_text(data, 'next')}",
+            ]
+        )
+
+    if event == "reviewer-running":
+        reviewer = _require_count(data, "reviewer", maximum=2)
+        if reviewer < 1:
+            raise ReportStateError("reviewer must be 1 or 2")
+        risk = _require_risk(data)
+        if risk == "low" or (risk == "medium" and reviewer == 2):
+            raise ReportStateError("reviewer exceeds the semantic risk limit")
+        attempt = data.get("attempt", 1)
+        if attempt not in {1, 2}:
+            raise ReportStateError("attempt must be 1 or 2")
+        return "\n".join(
+            [
+                f"## Independent Reviewer {reviewer}",
+                "",
+                "- Status: RUNNING",
+                f"- Risk Trigger: {risk}",
+                f"- Attempt: {attempt}",
+            ]
+        )
+
+    if event == "reviewer-result":
+        reviewer = _require_count(data, "reviewer", maximum=2)
+        if reviewer < 1:
+            raise ReportStateError("reviewer must be 1 or 2")
+        result = data.get("result")
+        if result not in {"PASS", "FINDINGS", "BLOCKED"}:
+            raise ReportStateError(f"result has invalid value: {result!r}")
+        findings = _require_count(data, "findings")
+        accepted = _require_count(data, "accepted")
+        rejected = _require_count(data, "rejected")
+        accepted_high = _require_count(data, "accepted_high")
+        if accepted + rejected != findings or accepted_high > accepted:
+            raise ReportStateError("reviewer finding counts are inconsistent")
+        status = "BLOCKED" if result == "BLOCKED" else "COMPLETED"
+        return "\n".join(
+            [
+                f"## Independent Reviewer {reviewer} Result",
+                "",
+                f"- Status: {status}",
+                f"- Result: {result}",
+                f"- Findings: {findings}",
+                f"- Accepted: {accepted}",
+                f"- Rejected: {rejected}",
+                f"- Accepted High: {accepted_high}",
+                f"- Next: {_require_text(data, 'next')}",
+            ]
+        )
+
+    if event == "infrastructure-failure":
+        reviewer = _require_count(data, "reviewer", maximum=2)
+        attempt = _require_count(data, "attempt", maximum=2)
+        if reviewer < 1 or attempt < 1:
+            raise ReportStateError("reviewer and attempt must be at least 1")
+        return "\n".join(
+            [
+                f"## Independent Reviewer {reviewer} Infrastructure Failure",
+                "",
+                f"- Attempt: {attempt}",
+                f"- Evidence: {_require_text(data, 'evidence')}",
+                f"- Next: {_require_text(data, 'next')}",
+            ]
+        )
+
+    return "\n".join(
+        [
+            "## Final Verification",
+            "",
+            f"- Status: {_require_text(data, 'status')}",
+            f"- Evidence: {_require_text(data, 'evidence')}",
+        ]
     )
-    blocker = data.get("blocker")
 
+
+def append_event(path: Path, data: Any) -> None:
+    """Append one validated progress event to an active execution."""
+    _ensure_appendable(path)
+    _append_section(path, _render_event(_require_object(data)))
+
+
+def append_final_result(path: Path, data: Any) -> None:
+    """Append the sole terminal result for the current execution."""
+    _ensure_appendable(path)
+    valid = _require_object(data)
+    verdict = valid.get("verdict")
+    if verdict not in VERDICTS:
+        raise ReportStateError(f"verdict has invalid value: {verdict!r}")
+    risk = _require_risk(valid)
+    main_rounds = _require_count(valid, "main_review_rounds", maximum=10)
+    reviewers = _require_count(valid, "independent_reviewers_started", maximum=2)
+    if reviewers > {"low": 0, "medium": 1, "high": 2}[risk]:
+        raise ReportStateError("independent_reviewers_started exceeds risk limit")
+    accepted = _require_count(valid, "accepted_findings")
+    fixed = _require_count(valid, "fixed_findings")
+    rejected = _require_count(valid, "rejected_findings")
+    unresolved = _require_count(valid, "unresolved_findings")
     if verdict == "PASS" and unresolved:
         raise ReportStateError("PASS cannot contain unresolved findings")
     if verdict == "NEEDS_FIXES" and not unresolved:
-        raise ReportStateError("NEEDS_FIXES requires an unresolved finding")
-    if verdict == "BLOCKED":
-        if not isinstance(blocker, str) or not blocker.strip():
-            raise ReportStateError("BLOCKED requires a non-empty blocker")
-        if unresolved:
-            raise ReportStateError("BLOCKED cannot classify code findings as unresolved")
-    elif blocker is not None:
-        raise ReportStateError("only BLOCKED may include blocker")
+        raise ReportStateError("NEEDS_FIXES requires unresolved findings")
 
-    return data
+    section = "\n".join(
+        [
+            FINAL_HEADING,
+            "",
+            f"- Verdict: {verdict}",
+            f"- Risk: {risk}",
+            f"- Main Review Rounds: {main_rounds}",
+            f"- Independent Reviewers Started: {reviewers}",
+            f"- Accepted Findings: {accepted}",
+            f"- Fixed Findings: {fixed}",
+            f"- Rejected Findings: {rejected}",
+            f"- Unresolved Findings: {unresolved}",
+            f"- Summary: {_require_text(valid, 'summary')}",
+        ]
+    )
+    _append_section(path, section)
 
 
-def _finding_totals(findings: list[dict[str, Any]]) -> tuple[int, int, int]:
-    fixed = sum(finding["disposition"].startswith("fixed") for finding in findings)
-    rejected = sum(
-        finding["disposition"].startswith("rejected") for finding in findings
-    )
-    unresolved = sum(
-        finding["disposition"].startswith("unresolved") for finding in findings
-    )
-    return fixed, rejected, unresolved
-
-
-def render_report(data: Any) -> str:
-    valid = validate_data(data)
-    findings = valid["findings"]
-    fixed, rejected, unresolved = _finding_totals(findings)
-
-    lines = [
-        "# Review Report",
-        "",
-        f"## Verdict: {valid['verdict']}",
-        f"## Rounds Completed: {valid['rounds_completed']}",
-        f"## Total Findings: {len(findings)} → Fixed: {fixed}, Rejected: {rejected}, Unresolved: {unresolved}",
-        "",
-    ]
-
-    if findings:
-        lines.extend(["## Findings", ""])
-        for index, finding in enumerate(findings, start=1):
-            lines.extend(
-                [
-                    f"### Finding {index}: {finding['title']}",
-                    "",
-                    f"- Severity: {finding['severity']}",
-                    f"- Location: {finding['location']}",
-                    f"- Problem: {finding['problem']}",
-                    f"- Failure Scenario: {finding['failure_scenario']}",
-                    f"- Disposition: {finding['disposition']}",
-                    "",
-                ]
-            )
-
-    if valid["verdict"] == "BLOCKED":
-        lines.extend(["## Blocker", "", valid["blocker"], ""])
-
-    lines.extend(["## Summary", "", valid["summary"], ""])
-    return "\n".join(lines)
+def _read_json_input() -> Any:
+    try:
+        return json.loads(sys.stdin.read())
+    except json.JSONDecodeError as error:
+        raise ReportStateError(f"invalid JSON input: {error}") from error
 
 
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("output", type=Path, help="review-report.md destination")
-    parser.add_argument(
-        "input",
-        nargs="?",
-        type=Path,
-        help="optional JSON input path; reads standard input when omitted",
-    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    for command in ("init", "append", "finalize"):
+        subparser = subparsers.add_parser(command)
+        subparser.add_argument("report", type=Path)
     return parser.parse_args()
 
 
 def main() -> int:
     args = parse_args()
     try:
-        raw = args.input.read_text(encoding="utf-8") if args.input else sys.stdin.read()
-        data = json.loads(raw)
-        report = render_report(data)
-        args.output.parent.mkdir(parents=True, exist_ok=True)
-        args.output.write_text(report, encoding="utf-8")
-    except (OSError, json.JSONDecodeError, ReportStateError, KeyError) as error:
+        if args.command == "init":
+            initialize_report(args.report)
+        elif args.command == "append":
+            append_event(args.report, _read_json_input())
+        else:
+            append_final_result(args.report, _read_json_input())
+    except (OSError, ReportStateError, KeyError) as error:
         print(json.dumps({"error": str(error)}, sort_keys=True))
         return 1
     return 0
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    raise SystemExit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.1.125",
+  "version": "1.1.127",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {