@topy-ai/maggie 0.7.20 → 0.7.22

package/bundled-tools/clis/maggie_deployment_readiness.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Summarize release evidence without confusing tests with runtime readiness."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+
+CHECKS = (
+    ("unitRegression", "unit_report"),
+    ("packageSmoke", "package_report"),
+    ("browserEvidence", "browser_report"),
+    ("renderedCanary", "rendered_canary"),
+    ("deploymentPreflight", "deployment_preflight"),
+)
+
+
+def display_path(path: Path, project: Path) -> str:
+    try:
+        return str(path.resolve().relative_to(project.resolve()))
+    except ValueError:
+        return path.name
+
+
+def validate_unit(payload: dict[str, Any]) -> tuple[bool, str]:
+    if payload.get("schemaVersion") != "maggie-regression.v1":
+        return False, "unit evidence schemaVersion is unsupported"
+    if payload.get("status") != "passed" or not isinstance(payload.get("suites"), int) or payload["suites"] < 1:
+        return False, "unit evidence must report a passing suite count"
+    if payload.get("skipped", 0) != 0:
+        return False, "unit evidence contains skipped suites"
+    return True, "dependency-free regression suites passed"
+
+
+def validate_package(payload: dict[str, Any]) -> tuple[bool, str]:
+    if payload.get("schemaVersion") != "maggie-package-smoke.v1":
+        return False, "package evidence schemaVersion is unsupported"
+    checks = payload.get("checks")
+    if payload.get("passed") is not True or not isinstance(checks, list) or not checks:
+        return False, "package evidence must contain passing smoke checks"
+    return True, "package smoke checks passed"
+
+
+def validate_browser(payload: dict[str, Any]) -> tuple[bool, str]:
+    if payload.get("schemaVersion") != "maggie-browser-evidence.v1":
+        return False, "browser evidence schemaVersion is unsupported"
+    routes = payload.get("routes")
+    if payload.get("passed") is not True or not isinstance(routes, list) or not routes:
+        return False, "browser evidence must contain a passing non-empty route set"
+    for route in routes:
+        if not isinstance(route, dict) or not route.get("route") or not route.get("screenshot"):
+            return False, "browser evidence routes need a route and screenshot"
+        if route.get("consoleErrors") or route.get("networkErrors") or route.get("missingAssets"):
+            return False, "browser evidence contains runtime errors"
+    return True, "host browser evidence passed"
+
+
+def validate_canary(payload: dict[str, Any]) -> tuple[bool, str]:
+    if payload.get("schemaVersion") != "maggie-deployment-canary.v1":
+        return False, "rendered canary schemaVersion is unsupported"
+    if payload.get("status") != "pass":
+        return False, "rendered canary did not pass"
+    rendered = payload.get("rendered")
+    if not isinstance(rendered, dict) or not isinstance(rendered.get("report"), dict):
+        return False, "rendered canary is missing browser-rendered report evidence"
+    return True, "edge and rendered canary passed"
+
+
+def validate_preflight(payload: dict[str, Any]) -> tuple[bool, str]:
+    if payload.get("schemaVersion") not in {"1.0", "maggie-release-preflight.v1"}:
+        return False, "deployment preflight schemaVersion is unsupported"
+    if payload.get("passed") is not True:
+        return False, "deployment preflight contains a failed gate"
+    gates = payload.get("gates")
+    if not isinstance(gates, list) or not gates:
+        return False, "deployment preflight has no gate results"
+    return True, "deployment preflight gates passed"
+
+
+VALIDATORS: dict[str, Callable[[dict[str, Any]], tuple[bool, str]]] = {
+    "unitRegression": validate_unit,
+    "packageSmoke": validate_package,
+    "browserEvidence": validate_browser,
+    "renderedCanary": validate_canary,
+    "deploymentPreflight": validate_preflight,
+}
+
+
+def inspect_check(name: str, path: Path, project: Path) -> dict[str, Any]:
+    result: dict[str, Any] = {"state": "inconclusive", "configured": path.is_file(), "path": display_path(path, project)}
+    if not path.is_file():
+        result["reason"] = "required adapter evidence is unavailable"
+        return result
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        result.update({"state": "failed", "reason": f"evidence is not valid JSON: {error}"})
+        return result
+    if not isinstance(payload, dict):
+        result.update({"state": "failed", "reason": "evidence root must be an object"})
+        return result
+    valid, reason = VALIDATORS[name](payload)
+    result.update({"state": "passed" if valid else "failed", "reason": reason})
+    return result
+
+
+def readiness(project: Path, paths: dict[str, Path], output: Path | None = None) -> int:
+    checks = {name: inspect_check(name, path, project) for name, path in paths.items()}
+    states = {item["state"] for item in checks.values()}
+    status = "failed" if "failed" in states else "inconclusive" if "inconclusive" in states else "passed"
+    report = {
+        "schemaVersion": "maggie-deployment-readiness.v1",
+        "generatedAt": datetime.now(timezone.utc).isoformat(),
+        "project": display_path(project, project),
+        "status": status,
+        "checks": checks,
+        "nextAction": "resolve failed evidence before release" if status == "failed" else "collect the missing host adapter evidence" if status == "inconclusive" else "all declared readiness evidence passed",
+    }
+    if output:
+        destination = output if output.is_absolute() else project / output
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        report["output"] = display_path(destination, project)
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0 if status == "passed" else 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--project", type=Path, default=Path.cwd())
+    parser.add_argument("--unit-report", type=Path, default=Path(".maggie/verification/unit-regression.json"))
+    parser.add_argument("--package-report", type=Path, default=Path(".maggie/verification/package-smoke.json"))
+    parser.add_argument("--browser-report", type=Path, default=Path(".maggie/verification/browser-evidence.json"))
+    parser.add_argument("--rendered-canary", type=Path, default=Path(".maggie/deployment-canary.json"))
+    parser.add_argument("--deployment-preflight", type=Path, default=Path(".maggie/release-preflight.json"))
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    project = args.project.resolve()
+    if not project.is_dir():
+        parser.error(f"project directory does not exist: {project}")
+    paths = {
+        name: (getattr(args, option).resolve() if getattr(args, option).is_absolute() else project / getattr(args, option))
+        for name, option in CHECKS
+    }
+    try:
+        return readiness(project, paths, args.output)
+    except (OSError, ValueError) as error:
+        print(f"BLOCKED: maggie deployment readiness: {error}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_localization.py

@@ -12,7 +12,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
-from content_localization import LANGUAGES, MARKETS, OPERATIONS, parse_locale, protected_field_changes, stale, valid_locale, validate_translation
+from content_localization import LANGUAGES, MARKETS, OPERATIONS, parse_locale, protected_field_changes, stale, valid_locale, validate_operation_quality, validate_translation
 from localization_runner import generate, process_adapter
 
 
@@ -250,6 +250,8 @@ def validate_job(path: Path, source_path: Path | None = None, render_path: Path
         errors.append("generationContract mode must match operation")
     if job.get("operation") == "rewrite" and not generation.get("allowStructuralRewrite"):
         errors.append("rewrite requires structural rewrite permission")
+    if job.get("operation") == "polish" and job.get("sourceLanguage") != job.get("targetLanguage"):
+        errors.append("polish must keep sourceLanguage and targetLanguage identical")
     errors.extend(validate_translation({
         "contentId": job.get("contentId"), "lang": job.get("targetLanguage"),
         "locale": job.get("targetLocale"), "translationGroupId": job.get("translationGroupId", f"tg-{job.get('contentId')}"),
@@ -260,6 +262,8 @@ def validate_job(path: Path, source_path: Path | None = None, render_path: Path
         })
     }, expected_lang=job.get("targetLanguage")))
     errors.extend(f"protected field changed without approval: {field}" for field in protected_field_changes(job.get("content", {}), translation))
+    quality_errors, quality = validate_operation_quality(job.get("content", {}), translation, job.get("operation", ""), job.get("review"))
+    errors.extend(quality_errors)
     if source_path:
         errors.extend(validate_source(source_path, job.get("sourceRevision")))
         source = load(source_path)
@@ -269,7 +273,7 @@ def validate_job(path: Path, source_path: Path | None = None, render_path: Path
             errors.append("translation sourceStringIds must link every extracted source string")
     if render_path:
         errors.extend(validate_render_report(render_path))
-    return {"passed": not errors, "errors": errors, "jobId": job.get("jobId"), "status": job.get("status")}
+    return {"passed": not errors, "errors": errors, "jobId": job.get("jobId"), "status": job.get("status"), "quality": quality}
 
 
 def preview(path: Path) -> int:

package/bundled-tools/clis/maggie_qa_workflow.py

@@ -22,6 +22,9 @@ from urllib.parse import urlsplit, urlunsplit
 DEFAULT_SCENARIOS = Path(".maggie") / "scenario-manifest.json"
 VALID_STATUSES = {"pending", "pass", "fail", "blocked", "inconclusive"}
 VALID_PHASES = {"test", "fix", "retest"}
+ASSERTION_SCHEMA = "maggie.qa-assertions.v1"
+RUNTIME_ASSERTION_TYPES = {"http-status", "final-url", "text-present", "text-absent", "meta", "link-absent", "redirect"}
+SOURCE_ASSERTION_TYPES = {"class-present", "class-absent", "markup-present", "markup-absent", "source-text"}
 SECRET_RE = re.compile(
     r"(?i)(bearer\s+|(?:api[_-]?key|token|secret|password|authorization|cookie)\s*[=:]\s*)[^\s,;]+"
 )
@@ -314,6 +317,86 @@ def export_run(args: argparse.Namespace) -> int:
     return 0
 
 
+def assertion_audit(args: argparse.Namespace) -> int:
+    """Ensure QA assertions test the served requirement, not edited source markup."""
+    project = project_root(args.project)
+    manifest_path = project_root(args.assertions) if Path(args.assertions).is_absolute() else project / args.assertions
+    manifest = load_json(manifest_path)
+    errors = []
+    records = manifest.get("assertions")
+    if manifest.get("schemaVersion") != ASSERTION_SCHEMA:
+        errors.append(f"manifest schemaVersion must be {ASSERTION_SCHEMA}")
+    if not isinstance(records, list) or not records:
+        errors.append("assertions must be a non-empty array")
+        records = []
+    seen = set()
+    audited = []
+    for index, item in enumerate(records):
+        item_errors = []
+        if not isinstance(item, dict):
+            audited.append({"id": f"assertion-{index + 1}", "passed": False, "errors": ["assertion must be an object"]})
+            continue
+        identifier = safe_text(item.get("id"), 120) or f"assertion-{index + 1}"
+        if identifier in seen:
+            item_errors.append("assertion id is duplicated")
+        seen.add(identifier)
+        if not safe_text(item.get("requirement"), 1000):
+            item_errors.append("requirement is required")
+        route = safe_text(item.get("route"), 500)
+        if not route or not route.startswith("/"):
+            item_errors.append("route must be a path on the tested site")
+        if item.get("transport") != "http":
+            item_errors.append("transport must be http runtime evidence")
+        evidence_data = item.get("evidence")
+        if not isinstance(evidence_data, dict):
+            item_errors.append("evidence must be an object")
+            evidence_data = {}
+        if not safe_text(evidence_data.get("screenshot"), 500):
+            item_errors.append("evidence.screenshot is required")
+        if not isinstance(evidence_data.get("httpStatus"), int) or isinstance(evidence_data.get("httpStatus"), bool):
+            item_errors.append("evidence.httpStatus must be an integer")
+        checks = item.get("checks")
+        if not isinstance(checks, list) or not checks:
+            item_errors.append("checks must be a non-empty array")
+            checks = []
+        if not any(isinstance(check, dict) and check.get("type") == "http-status" for check in checks):
+            item_errors.append("at least one http-status check is required")
+        for check_index, check in enumerate(checks):
+            if not isinstance(check, dict):
+                item_errors.append(f"checks[{check_index}] must be an object")
+                continue
+            check_type = check.get("type")
+            surface = check.get("surface")
+            if check_type in SOURCE_ASSERTION_TYPES or surface == "source":
+                item_errors.append(f"checks[{check_index}] is source/markup-only; assert the served route instead")
+            if check_type not in RUNTIME_ASSERTION_TYPES:
+                item_errors.append(f"checks[{check_index}] has an unsupported runtime assertion type")
+            if surface not in {"http", "browser-runtime"}:
+                item_errors.append(f"checks[{check_index}] must identify http or browser-runtime evidence")
+            if not isinstance(check.get("passed"), bool):
+                item_errors.append(f"checks[{check_index}].passed must be boolean evidence")
+            if check_type == "http-status" and isinstance(evidence_data.get("httpStatus"), int) and check.get("actual") != evidence_data["httpStatus"]:
+                item_errors.append(f"checks[{check_index}] actual status does not match evidence.httpStatus")
+        if any(isinstance(check, dict) and check.get("passed") is False for check in checks):
+            item_errors.append("one or more runtime checks failed")
+        audited.append({"id": identifier, "passed": not item_errors, "errors": item_errors})
+    passed = not errors and all(item.get("passed") for item in audited) and bool(audited)
+    report = {
+        "schemaVersion": "maggie.qa-assertion-audit.v1",
+        "assertionSchema": ASSERTION_SCHEMA,
+        "checked": len(audited),
+        "assertions": audited,
+        "errors": errors,
+        "passed": passed,
+    }
+    output = Path(args.output).expanduser()
+    if not output.is_absolute():
+        output = project / output
+    write_json(output, report)
+    print(json.dumps({"status": "passed" if passed else "failed", "report": str(output.resolve()), "checked": len(audited), "errors": errors}, ensure_ascii=False, indent=2))
+    return 0 if passed else 1
+
+
 def parser() -> argparse.ArgumentParser:
     root = argparse.ArgumentParser(description=__doc__)
     root.add_argument("--project", default=".")
@@ -350,6 +433,10 @@ def parser() -> argparse.ArgumentParser:
         command.add_argument("--run", required=True)
         if name == "summary": command.add_argument("--format", choices=("json", "markdown"), default="json")
         else: command.add_argument("--output", required=True)
+    assertion_parser = commands.add_parser("assertion-audit")
+    assertion_parser.add_argument("--project", default=argparse.SUPPRESS)
+    assertion_parser.add_argument("--assertions", required=True, help="runtime assertion manifest JSON")
+    assertion_parser.add_argument("--output", default=".maggie/qa-assertion-audit.json")
     return root
 
 
@@ -359,6 +446,7 @@ def main() -> int:
         if args.command == "start": return start(args)
         if args.command == "record": return record(args)
         if args.command == "summary": return summary(args)
+        if args.command == "assertion-audit": return assertion_audit(args)
         return export_run(args)
     except (OSError, ValueError, json.JSONDecodeError) as error:
         print(f"QA workflow error: {safe_text(error)}", file=sys.stderr)