@deftai/directive-content 0.55.2 → 0.56.0

package/scripts/spec_validate.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""
+spec_validate.py — Validate a vbrief specification JSON file.
+
+Usage:
+    uv run python scripts/spec_validate.py <spec_file>
+
+Exit codes:
+    0 — valid
+    1 — invalid (file missing, bad JSON, or schema violation)
+    2 — usage error (no argument provided)
+
+Implementation: IMPLEMENTATION.md Phase 5.1
+"""
+
+import json
+import sys
+from pathlib import Path
+
+# Belt-and-suspenders UTF-8 stdout guard (#540) so non-ASCII status glyphs
+# do not crash on Windows cp1252 when the ``PYTHONUTF8`` env var is not set.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _stdio_utf8 import reconfigure_stdio  # noqa: E402
+
+reconfigure_stdio()
+
+# v0.6 Status enum (includes the new ``failed`` terminal status per
+# the canonical schema at vbrief/schemas/vbrief-core.schema.json, #533).
+VALID_STATUSES = frozenset({
+    "draft", "proposed", "approved", "pending",
+    "running", "completed", "blocked", "failed", "cancelled",
+})
+
+
+def _validate_narratives(narratives: object, path: str, errors: list[str]) -> None:
+    """Validate that all values in a narratives/narrative object are strings."""
+    if not isinstance(narratives, dict):
+        errors.append(f"{path} must be an object")
+        return
+    for key, value in narratives.items():
+        if not isinstance(value, str):
+            errors.append(
+                f"{path}.{key} must be a string, got {type(value).__name__}"
+            )
+
+
+def _validate_plan_item(
+    item: dict, path: str, errors: list[str],
+) -> None:
+    """Recursively validate a PlanItem and its nested children.
+
+    Per the canonical v0.6 schema, ``PlanItem.items`` is the PREFERRED
+    nested field and ``PlanItem.subItems`` is the deprecated legacy alias
+    kept for backward compatibility (#533 / Greptile P1). Both are accepted
+    here and recursively validated; neither is treated as an error.
+    """
+    item_id = item.get("id", "<no-id>")
+    item_path = f"{path}[{item_id}]"
+
+    if "title" not in item:
+        errors.append(f"{item_path} missing 'title'")
+    if "status" not in item:
+        errors.append(f"{item_path} missing 'status'")
+    elif item["status"] not in VALID_STATUSES:
+        errors.append(
+            f"{item_path} invalid status: {item['status']!r}"
+        )
+
+    # Narrative values must be strings
+    if "narrative" in item:
+        _validate_narratives(item["narrative"], f"{item_path}.narrative", errors)
+
+    # v0.6 preferred nested field.
+    if "items" in item:
+        if not isinstance(item["items"], list):
+            errors.append(f"{item_path}.items must be an array")
+        else:
+            for j, sub in enumerate(item["items"]):
+                if not isinstance(sub, dict):
+                    errors.append(f"{item_path}.items[{j}] must be an object")
+                    continue
+                _validate_plan_item(sub, f"{item_path}.items", errors)
+
+    # Deprecated legacy alias -- still accepted for backward compatibility.
+    if "subItems" in item:
+        if not isinstance(item["subItems"], list):
+            errors.append(f"{item_path}.subItems must be an array")
+        else:
+            for j, sub in enumerate(item["subItems"]):
+                if not isinstance(sub, dict):
+                    errors.append(f"{item_path}.subItems[{j}] must be an object")
+                    continue
+                _validate_plan_item(sub, f"{item_path}.subItems", errors)
+
+
+# Strict v0.6-only acceptance (#533). The canonical schema at
+# vbrief/schemas/vbrief-core.schema.json pins vBRIEFInfo.version to
+# const "0.6"; this validator rejects every other version. Pre-existing
+# v0.5 vBRIEFs are automatically bumped to v0.6 during ``task
+# migrate:vbrief`` (#571); operators who see the error below should run
+# the migrator on the affected project. The check below consults this
+# frozenset rather than an inline literal so the validator shares the
+# version-check pattern with ``scripts/vbrief_validate.py`` (#565,
+# Option B): future v0.7 introduction adds one entry here instead of
+# touching multiple inline string comparisons.
+VALID_VBRIEF_VERSIONS: frozenset[str] = frozenset({"0.6"})
+
+
+def _validate_schema(data: dict, path: str) -> list[str]:
+    """Validate vBRIEF structural requirements (v0.6). Returns a list of errors.
+
+    Strictly requires ``vBRIEFInfo.version`` to be one of
+    ``VALID_VBRIEF_VERSIONS`` (currently ``{"0.6"}``) to match the
+    canonical v0.6 schema (#533). Any v0.5 vBRIEF must be migrated to
+    v0.6 via ``task migrate:vbrief``.
+    """
+    errors: list[str] = []
+
+    # Top-level envelope
+    if "vBRIEFInfo" not in data:
+        errors.append("missing required top-level key 'vBRIEFInfo'")
+    else:
+        info = data["vBRIEFInfo"]
+        if not isinstance(info, dict):
+            errors.append("'vBRIEFInfo' must be an object")
+        elif info.get("version") not in VALID_VBRIEF_VERSIONS:
+            # #571: the previous wording pointed at a "migrator sweep"
+            # that did not exist as a standalone command, leaving
+            # operators with an unactionable error. The migrator now
+            # auto-bumps v0.5 -> v0.6 on ingest (see
+            # ``scripts/migrate_vbrief.py`` ``_ingest_spec_narratives``
+            # path), so the actionable recovery command is just
+            # ``task migrate:vbrief``.
+            #
+            # #565: the version comparison consults
+            # ``VALID_VBRIEF_VERSIONS`` rather than an inline ``"0.6"``
+            # literal so this validator matches the
+            # ``scripts/vbrief_validate.py`` pattern (Option B).
+            errors.append(
+                f"'vBRIEFInfo.version' must be '0.6' (canonical v0.6 "
+                f"schema, #533), got {info.get('version')!r}. Run "
+                f"`task migrate:vbrief` to upgrade pre-existing v0.5 "
+                f"vBRIEFs in-place."
+            )
+
+    if "plan" not in data:
+        errors.append("missing required top-level key 'plan'")
+    else:
+        plan = data["plan"]
+        if not isinstance(plan, dict):
+            errors.append("'plan' must be an object, not a string or other type")
+        else:
+            for field in ("title", "status", "items"):
+                if field not in plan:
+                    errors.append(f"'plan' missing required field '{field}'")
+
+            if "title" in plan and (not isinstance(plan["title"], str) or not plan["title"]):
+                errors.append("'plan.title' must be a non-empty string")
+
+            if "status" in plan and plan["status"] not in VALID_STATUSES:
+                errors.append(
+                    f"'plan.status' invalid: {plan['status']!r} "
+                    f"(expected one of {sorted(VALID_STATUSES)})"
+                )
+
+            # Validate plan-level narratives
+            if "narratives" in plan:
+                _validate_narratives(
+                    plan["narratives"], "plan.narratives", errors
+                )
+
+            if "items" in plan:
+                if not isinstance(plan["items"], list):
+                    errors.append("'plan.items' must be an array")
+                else:
+                    for i, item in enumerate(plan["items"]):
+                        if not isinstance(item, dict):
+                            errors.append(f"plan.items[{i}] must be an object")
+                            continue
+                        _validate_plan_item(item, "plan.items", errors)
+
+    # Detect legacy flat format. Per #565, the migration target message
+    # advertises the canonical v0.6 envelope (the prior wording pointed
+    # at the retired v0.5 envelope after the strict v0.6 tightening in
+    # #533).
+    legacy_keys = {"vbrief", "tasks", "overview", "architecture"}
+    found_legacy = legacy_keys & set(data.keys())
+    if found_legacy:
+        errors.append(
+            f"legacy flat-format keys found at top level: {sorted(found_legacy)}. "
+            "Migrate to vBRIEF v0.6 envelope (vBRIEFInfo + plan)"
+        )
+
+    return errors
+
+
+def validate_spec(spec_path: str) -> tuple[bool, str]:
+    """
+    Validate the spec file at *spec_path*.
+
+    Returns:
+        (True, success_message) on success.
+        (False, error_message)  on failure.
+    """
+    path = Path(spec_path)
+    if not path.exists():
+        return (
+            False,
+            f"✗ {spec_path} not found\n"
+            "  Create it by running the interview process "
+            "(see deft/templates/make-spec.md)",
+        )
+    try:
+        with open(path, encoding="utf-8") as fh:
+            data = json.load(fh)
+    except json.JSONDecodeError as exc:
+        return False, f"✗ {spec_path} is not valid JSON: {exc}"
+
+    errors = _validate_schema(data, spec_path)
+    if errors:
+        detail = "\n".join(f"  • {e}" for e in errors)
+        return False, f"✗ {path.name} has schema violations:\n{detail}"
+
+    return True, f"✓ {path.name} is valid vBRIEF"
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("Usage: spec_validate.py <spec_file>", file=sys.stderr)
+        return 2
+
+    ok, message = validate_spec(sys.argv[1])
+    print(message)
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())