@topy-ai/maggie 0.7.4 → 0.7.6

package/bundled-tools/runtime/surface_coverage.py

@@ -0,0 +1,122 @@
+"""Coverage checks that follow the surface and locale changed by a release."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+SCHEMA = "maggie-surface-coverage.v1"
+REQUIRED_EVIDENCE = ("status", "canonical", "indexability", "metadata")
+
+
+def validate_contract(contract: object) -> dict[str, Any]:
+    errors: list[str] = []
+    if not isinstance(contract, dict):
+        return {"schemaVersion": SCHEMA, "passed": False, "errors": ["coverage contract must be an object"]}
+    if contract.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    surfaces = contract.get("surfaces")
+    if not isinstance(surfaces, list) or not surfaces:
+        errors.append("surfaces must be a non-empty list")
+        surfaces = []
+    seen: set[tuple[str, str]] = set()
+    for index, item in enumerate(surfaces):
+        if not isinstance(item, dict) or not item.get("name") or not isinstance(item.get("routes"), list) or not item["routes"] or not isinstance(item.get("locales"), list) or not item["locales"]:
+            errors.append(f"surfaces[{index}] needs name, routes, and locales")
+            continue
+        required = item.get("requiredEvidence")
+        if not isinstance(required, list) or not required or any(value not in REQUIRED_EVIDENCE for value in required):
+            errors.append(f"surfaces[{index}] needs valid requiredEvidence")
+        metadata = item.get("requiredMetadata")
+        if not isinstance(metadata, list) or any(not isinstance(value, str) or not value for value in metadata):
+            errors.append(f"surfaces[{index}] needs requiredMetadata")
+        route_values = [str(route) for route in item["routes"]]
+        if len(route_values) != len(set(route_values)):
+            errors.append(f"duplicate route in surface: {item['name']}")
+        locale_values = [str(locale) for locale in item["locales"]]
+        if len(locale_values) != len(set(locale_values)):
+            errors.append(f"duplicate locale in surface: {item['name']}")
+        for locale in item["locales"]:
+            key = (str(item["name"]), str(locale))
+            if key in seen:
+                errors.append(f"duplicate surface/locale: {key[0]}/{key[1]}")
+            seen.add(key)
+    expected = [f"{item['name']}/{locale}/{route}" for item in surfaces if isinstance(item, dict) and item.get("name") for locale in item.get("locales", []) for route in item.get("routes", [])]
+    return {"schemaVersion": SCHEMA, "passed": not errors, "errors": errors, "expectedPairs": sorted(f"{surface}/{locale}" for surface, locale in seen), "expectedRoutes": sorted(expected)}
+
+
+def _truthy_check(value: object) -> bool:
+    if value is True:
+        return True
+    return isinstance(value, dict) and value.get("ok") is True
+
+
+def _key_text(key: tuple[str, str, str]) -> str:
+    return f"{key[0]}/{key[1]}|{key[2]}"
+
+
+def _route_result(item: dict[str, Any], required: list[str], required_metadata: list[str]) -> tuple[bool, list[str]]:
+    missing: list[str] = []
+    checks = item.get("checks") if isinstance(item.get("checks"), dict) else {}
+    if "status" in required:
+        try:
+            if int(item.get("status")) >= 400:
+                missing.append("status")
+        except (TypeError, ValueError):
+            missing.append("status")
+    if "canonical" in required and not _truthy_check(item.get("canonical", checks.get("canonical"))):
+        missing.append("canonical")
+    indexability = item.get("indexable", item.get("indexability", checks.get("indexability")))
+    if "indexability" in required and not isinstance(indexability, bool):
+        missing.append("indexability")
+    if "metadata" in required:
+        metadata = item.get("metadata") if isinstance(item.get("metadata"), dict) else checks.get("metadata")
+        if not isinstance(metadata, dict) or any(metadata.get(field) is not True for field in required_metadata):
+            missing.append("metadata")
+    if item.get("passed") is not True:
+        missing.append("passed")
+    return not missing, sorted(set(missing))
+
+
+def compare(contract: dict[str, Any], observations: object) -> dict[str, Any]:
+    checked = validate_contract(contract)
+    if not checked["passed"]:
+        return {**checked, "observedPairs": [], "missing": [], "failed": []}
+    expected = {(str(item["name"]), str(locale), str(route)) for item in contract["surfaces"] for locale in item["locales"] for route in item["routes"]}
+    observed: dict[tuple[str, str, str], dict[str, Any]] = {}
+    duplicate_keys: list[str] = []
+    observation_count = 0
+    route_results: list[dict[str, Any]] = []
+    for item in observations if isinstance(observations, list) else []:
+        if not isinstance(item, dict):
+            continue
+        observation_count += 1
+        key = (str(item.get("surface") or ""), str(item.get("locale") or ""), str(item.get("route") or ""))
+        if key in expected:
+            if key in observed:
+                duplicate_keys.append(_key_text(key))
+            else:
+                observed[key] = item
+    missing = sorted(_key_text(key) for key in expected - observed.keys())
+    failed: list[str] = []
+    for key, item in observed.items():
+        surface = next(value for value in contract["surfaces"] if str(value["name"]) == key[0])
+        passed, missing_evidence = _route_result(item, list(surface["requiredEvidence"]), list(surface["requiredMetadata"]))
+        key_text = _key_text(key)
+        route_results.append({"route": key_text, "passed": passed, "missingEvidence": missing_evidence})
+        if not passed:
+            failed.append(key_text)
+    failed = sorted(set(failed))
+    return {
+        "schemaVersion": SCHEMA,
+        "passed": not missing and not failed and not duplicate_keys,
+        "expectedPairs": sorted(f"{surface}/{locale}" for surface, locale, _route in expected),
+        "expectedRoutes": sorted(_key_text(key) for key in expected),
+        "observedPairs": sorted(f"{surface}/{locale}" for surface, locale, _route in observed),
+        "observedRoutes": sorted(_key_text(key) for key in observed),
+        "observationCount": observation_count,
+        "duplicates": sorted(set(duplicate_keys)),
+        "missing": missing,
+        "failed": failed,
+        "routeResults": sorted(route_results, key=lambda value: value["route"]),
+    }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/localization-extraction-render-prd.md

@@ -0,0 +1,55 @@
+# Localization source extraction and rendered validation
+
+## Problem
+
+`maggie-content-localization` currently accepts a prepared `content.json` and
+validates the resulting job. It does not extract translatable strings from a
+real project, so malformed JSX fragments, multiline text nodes, untranslated
+Latin terms, and script mismatches can pass the record validator while still
+breaking the rendered page.
+
+## Proposed stable workflow
+
+Add a read-only extractor and a separate rendered validation gate:
+
+```bash
+maggie localization extract --project . --source-dir src \
+  --routes-file docs/routes.tsv --output .maggie/localization/source.json
+maggie localization plan --content .maggie/localization/source.json ...
+maggie localization validate .maggie/localization/<job>.json \
+  --source .maggie/localization/source.json \
+  --render-report .maggie/localization/rendered.json
+```
+
+The extractor must use an AST-aware adapter for JSX/TSX/Astro/Vue/Svelte
+where available, with a conservative HTML fallback. It must never rewrite
+source files. Each extracted string records file, line, route, source hash,
+attribute/text-node kind, and an explicit translatable/non-translatable
+decision. Fragments containing braces or JavaScript operators are rejected or
+reported for review, not interpreted as text.
+
+The validation report must cover multiline nodes, required metadata, protected
+facts, script expectations, glossary/allowlist exceptions, and browser output.
+The rendered report must identify route, screenshot, console errors, failed
+asset requests, placeholder count, and untranslated required strings. Any
+failure keeps the locale non-indexable and blocks publish.
+
+## Acceptance criteria
+
+- JSX conditionals and expressions are never emitted as translation strings.
+- Text nodes spanning multiple lines are extracted and tested.
+- Script/Latin-word checks support all registered languages and configurable
+  proper-noun/glossary allowlists.
+- Source and translated strings are linked by stable IDs and source revision.
+- A clean extraction plus clean rendered report is required before approval;
+  record-only validation is not sufficient.
+- Unit fixtures cover Astro/JSX/Vue/Svelte/HTML, false positives, protected
+  facts, multiline nodes, script checks, and route-level browser errors.
+- The feature remains local-first, dependency-adaptable, redacted, and
+  backward-compatible with existing `content.json` input.
+
+## Out of scope
+
+Automatic translation quality scoring, silent source rewriting, and automatic
+publish. Translation generation and owner/Admin approval remain separate
+operations.