@deftai/directive-content 0.58.0 → 0.60.0

package/scripts/spec_validate.py

@@ -1,238 +0,0 @@
-#!/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())