prizmkit 1.1.86 → 1.1.87

package/bundled/skills-windows/prizmkit-test/scripts/validate_boundary_report.py

@@ -0,0 +1,347 @@
+#!/usr/bin/env python3
+"""
+Validate a prizmkit-test report's boundary coverage gate.
+
+Usage:
+  python3 scripts/validate_boundary_report.py --report .prizmkit/test/.../test-report.md
+  python3 scripts/validate_boundary_report.py --report .prizmkit/test/.../test-report.md --openapi openapi.yaml
+
+The script intentionally performs deterministic structural checks only. It cannot prove that every
+business boundary is semantically correct, but it prevents reports from silently claiming completion
+when interfaces are missing from the Boundary Matrix or remain happy-path-only / boundary-missing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from typing import Dict, List, Set, Tuple
+
+ALLOWED_FINAL_STATUSES = {
+    "boundary-covered",
+    "generated-needs-review",
+    "skipped-with-reason",
+}
+INCOMPLETE_MARKERS = {
+    "boundary-missing",
+    "happy-path-only",
+    "unresolved",
+}
+REQUIRED_SECTIONS = [
+    "## Boundary Matrix",
+    "## Boundary Completion Gate",
+    "## Final Status",
+]
+REQUIRED_BOUNDARY_COLUMNS = [
+    "Module",
+    "Interface",
+    "Service Type",
+    "Happy Path",
+    "Request Validation",
+    "Auth / Permission / Ownership",
+    "Domain Invariants",
+    "Collection / Pagination",
+    "Date / Time",
+    "State Transitions",
+    "Dependency Failure",
+    "Response Contract",
+    "N/A Reasons",
+    "Final Status",
+]
+BOUNDARY_CATEGORY_COLUMNS = [
+    "Happy Path",
+    "Request Validation",
+    "Auth / Permission / Ownership",
+    "Domain Invariants",
+    "Collection / Pagination",
+    "Date / Time",
+    "State Transitions",
+    "Dependency Failure",
+    "Response Contract",
+]
+
+
+def read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        raise SystemExit(f"FAIL: file not found: {path}")
+
+
+HTTP_METHODS = {"GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "TRACE"}
+
+
+def extract_openapi_paths(openapi_text: str) -> List[str]:
+    """Extract OpenAPI path keys without requiring PyYAML.
+
+    Supports common YAML forms inside the `paths:` mapping:
+    - /users:
+    - "/users/{id}":
+    - '/users/{id}':
+    """
+    return [path for _method, path in extract_openapi_operations(openapi_text)]
+
+
+def extract_openapi_operations(openapi_text: str) -> List[Tuple[str, str]]:
+    """Extract OpenAPI method+path operations without requiring PyYAML."""
+    operations: List[Tuple[str, str]] = []
+    in_paths = False
+    paths_indent = 0
+    current_path = ""
+    current_path_indent = 0
+    path_key_re = re.compile(
+        r"^\s*(?:(['\"])(/.*?)\1|(/[^:\s]+))\s*:\s*(?:#.*)?$"
+    )
+    method_re = re.compile(r"^\s*([A-Za-z]+)\s*:\s*(?:#.*)?$")
+
+    for raw_line in openapi_text.splitlines():
+        stripped = raw_line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        indent = len(raw_line) - len(raw_line.lstrip())
+        if not in_paths:
+            if re.match(r"^\s*paths\s*:\s*(?:#.*)?$", raw_line):
+                in_paths = True
+                paths_indent = indent
+            continue
+
+        if indent <= paths_indent:
+            break
+
+        path_match = path_key_re.match(raw_line)
+        if path_match:
+            current_path = path_match.group(2) or path_match.group(3) or ""
+            current_path_indent = indent
+            continue
+
+        method_match = method_re.match(raw_line)
+        if current_path and method_match and indent > current_path_indent:
+            method = method_match.group(1).upper()
+            if method in HTTP_METHODS:
+                operations.append((method, current_path))
+
+    return operations
+
+
+def extract_section(text: str, heading: str) -> str:
+    start = text.find(heading)
+    if start == -1:
+        return ""
+    rest = text[start + len(heading) :]
+    match = re.search(r"\n## ", rest)
+    if not match:
+        return rest
+    return rest[: match.start()]
+
+
+def split_markdown_row(line: str) -> List[str]:
+    return [cell.strip() for cell in line.strip().strip("|").split("|")]
+
+
+def parse_boundary_matrix(text: str) -> Tuple[List[str], List[Dict[str, str]]]:
+    section = extract_section(text, "## Boundary Matrix")
+    if not section:
+        return [], []
+
+    lines = [line.strip() for line in section.splitlines() if line.strip().startswith("|")]
+    header_index = -1
+    for idx, line in enumerate(lines):
+        cells = split_markdown_row(line)
+        if "Interface" in cells and "Final Status" in cells:
+            header_index = idx
+            break
+    if header_index == -1:
+        return [], []
+
+    headers = split_markdown_row(lines[header_index])
+    rows: List[Dict[str, str]] = []
+    for line in lines[header_index + 1 :]:
+        cells = split_markdown_row(line)
+        if all(re.fullmatch(r":?-{3,}:?", cell) for cell in cells):
+            continue
+        if len(cells) < len(headers):
+            cells.extend([""] * (len(headers) - len(cells)))
+        row = {header: cells[i] if i < len(cells) else "" for i, header in enumerate(headers)}
+        # Ignore example placeholder rows that were accidentally left in templates.
+        if row.get("Interface", "").strip(".` ") in {"...", ""}:
+            continue
+        rows.append(row)
+    return headers, rows
+
+
+def has_inline_reason(value: str) -> bool:
+    normalized = value.strip().lower()
+    if not normalized:
+        return False
+    if "—" in value or " - " in value or ":" in value:
+        return True
+    # Accept phrases longer than a bare status marker.
+    bare = {"n/a", "na", "skipped", "skip"}
+    return normalized not in bare and (normalized.startswith("n/a ") or normalized.startswith("skipped "))
+
+
+def extract_matrix_operations(interface_values: List[str]) -> Tuple[Set[Tuple[str, str]], Set[str]]:
+    """Extract method+path and path-only tokens from Boundary Matrix Interface cells."""
+    operations: Set[Tuple[str, str]] = set()
+    path_only: Set[str] = set()
+    token_re = re.compile(
+        r"(?:(\b(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|TRACE)\b)\s+)?(/[^\s,`|)]+)",
+        flags=re.IGNORECASE,
+    )
+    for value in interface_values:
+        for match in token_re.finditer(value):
+            method = match.group(1).upper() if match.group(1) else ""
+            path = normalize_path(match.group(2))
+            if not path:
+                continue
+            if method:
+                operations.add((method, path))
+            else:
+                path_only.add(path)
+    return operations, path_only
+
+
+def normalize_path(path: str) -> str:
+    normalized = path.strip().strip("'\"`")
+    if len(normalized) > 1:
+        normalized = normalized.rstrip("/")
+    return normalized
+
+
+def validate_report(report_text: str, openapi_paths: List[str] | None,
+                    openapi_operations: List[Tuple[str, str]] | None = None) -> List[str]:
+    errors: List[str] = []
+
+    for section in REQUIRED_SECTIONS:
+        if section not in report_text:
+            errors.append(f"missing required section: {section}")
+
+    headers, rows = parse_boundary_matrix(report_text)
+    if not rows:
+        errors.append("Boundary Matrix table is missing or empty")
+        return errors
+
+    for column in REQUIRED_BOUNDARY_COLUMNS:
+        if column not in headers:
+            errors.append(f"Boundary Matrix missing required column: {column}")
+
+    final_statuses = []
+    interface_values = []
+    for idx, row in enumerate(rows, start=1):
+        interface = row.get("Interface", "").strip()
+        interface_values.append(interface)
+
+        final_status = row.get("Final Status", "").strip().lower()
+        final_statuses.append(final_status)
+        if not final_status:
+            errors.append(f"row {idx} ({interface}) missing Final Status")
+        elif final_status not in ALLOWED_FINAL_STATUSES:
+            errors.append(
+                f"row {idx} ({interface}) has invalid/incomplete Final Status: {row.get('Final Status', '')}"
+            )
+
+        for column in BOUNDARY_CATEGORY_COLUMNS:
+            if column in headers and not row.get(column, "").strip():
+                errors.append(f"row {idx} ({interface}) missing boundary category value: {column}")
+
+        for header, value in row.items():
+            normalized = value.strip().lower()
+            if any(marker in normalized for marker in INCOMPLETE_MARKERS):
+                errors.append(f"row {idx} ({interface}) has incomplete marker in {header}: {value}")
+
+        n_a_reasons = row.get("N/A Reasons", "").strip()
+        for header, value in row.items():
+            if header in {"Module", "Interface", "Service Type", "Final Status", "N/A Reasons"}:
+                continue
+            normalized = value.strip().lower()
+            if normalized in {"n/a", "na", "skipped", "skip"} and not n_a_reasons:
+                errors.append(f"row {idx} ({interface}) marks {header} as {value} without N/A reason")
+            if ("skipped" in normalized or normalized.startswith("n/a")) and not (n_a_reasons or has_inline_reason(value)):
+                errors.append(f"row {idx} ({interface}) marks {header} as {value} without concrete reason")
+
+    if openapi_operations is not None:
+        matrix_operations, matrix_path_only = extract_matrix_operations(interface_values)
+        for method, path in openapi_operations:
+            normalized_path = normalize_path(path)
+            if (method, normalized_path) not in matrix_operations:
+                if normalized_path in matrix_path_only:
+                    errors.append(
+                        "OpenAPI operation missing from Boundary Matrix: "
+                        f"{method} {path} (path-only row is ambiguous)"
+                    )
+                else:
+                    errors.append(
+                        f"OpenAPI operation missing from Boundary Matrix: {method} {path}"
+                    )
+    elif openapi_paths is not None:
+        _matrix_operations, matrix_path_only = extract_matrix_operations(interface_values)
+        missing_paths = [path for path in openapi_paths
+                         if normalize_path(path) not in matrix_path_only]
+        for path in missing_paths:
+            errors.append(f"OpenAPI path missing from Boundary Matrix: {path}")
+
+    gate_section = extract_section(report_text, "## Boundary Completion Gate")
+    if gate_section:
+        for label in ["Interfaces total", "Boundary-covered", "Boundary-missing", "Happy-path-only", "Completion gate passed"]:
+            if label not in gate_section:
+                errors.append(f"Boundary Completion Gate missing metric: {label}")
+        for label in ["Boundary-missing", "Happy-path-only"]:
+            match = re.search(rf"{re.escape(label)}:\s*(\d+)", gate_section)
+            if match and int(match.group(1)) > 0:
+                errors.append(f"Boundary Completion Gate reports {label}: {match.group(1)}")
+        if re.search(r"Completion gate passed:\s*no", gate_section, flags=re.IGNORECASE):
+            errors.append("Boundary Completion Gate reports failure")
+
+    final_section = extract_section(report_text, "## Final Status")
+    if final_section:
+        if re.search(r"Ready for commit:\s*yes", final_section, flags=re.IGNORECASE):
+            if any(status != "boundary-covered" for status in final_statuses):
+                errors.append("Final Status says ready for commit but not every interface is boundary-covered")
+            review_match = re.search(r"Needs human review:\s*(.+)", final_section, flags=re.IGNORECASE)
+            if review_match and review_match.group(1).strip().lower() not in {"none", "no", "n/a", ""}:
+                errors.append("Final Status says ready for commit while human review is still needed")
+
+    return errors
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate prizmkit-test boundary coverage report")
+    parser.add_argument("--report", required=True, help="Path to test-report.md")
+    parser.add_argument("--openapi", help="Optional OpenAPI file whose paths must appear in Boundary Matrix")
+    args = parser.parse_args()
+
+    report_path = Path(args.report)
+    report_text = read_text(report_path)
+
+    openapi_paths = None
+    openapi_operations = None
+    if args.openapi:
+        openapi_path = Path(args.openapi)
+        if openapi_path.exists():
+            openapi_text = read_text(openapi_path)
+            openapi_operations = extract_openapi_operations(openapi_text)
+            openapi_paths = [path for _method, path in openapi_operations]
+        else:
+            print(f"WARN: OpenAPI file not found, skipping path coverage check: {openapi_path}")
+
+    errors = validate_report(report_text, openapi_paths, openapi_operations)
+    if errors:
+        print("Boundary report validation: FAIL")
+        for error in errors:
+            print(f"- {error}")
+        return 1
+
+    print("Boundary report validation: PASS")
+    print(f"Report: {report_path}")
+    if openapi_operations is not None:
+        print(f"OpenAPI operations checked: {len(openapi_operations)}")
+    elif openapi_paths is not None:
+        print(f"OpenAPI paths checked: {len(openapi_paths)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/package.json

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