#!/usr/bin/env python3
"""Validate a deck op-sequence before BuildDeck (the VBA interpreter) runs it.

The op sequence (see references/deckops-spec.md) is newline-separated; each line
is an op name then US (Chr 31, "\\x1f")-delimited fields. The agent emits it by
judgment, so a fast deterministic check catches typos / wrong arity / bad state
(e.g. CELL before a TABLE) up front instead of part-building a deck in PowerPoint.

This is the deterministic, unit-tested half of #57 Phase D; BuildDeck itself is
manual-validation-only (it drives PowerPoint).

Usage:
    validate-deckops.py <ops-file>   # exit 0 + JSON summary, or exit 1 + errors on stderr
"""

import json
import sys
from pathlib import Path

US = "\x1f"

# op -> (exact field count including the op) or (min count, None) for variadic.
ARITY = {
    "SLIDE": (2, 2),
    "TITLE": (2, 2),
    "SUBTITLE": (2, 2),
    "BODY": (2, 2),
    "FOOTER": (2, 2),
    "CAT": (2, 2),
    "BULLET": (3, 3),
    "TEXT": (6, 6),
    "IMAGE": (6, 6),
    "SHAPE": (6, 6),
    "BG": (4, 4),
    "OPTIMIZE": (1, 1),
    "TABLE": (7, 7),
    "CELL": (4, 4),
    "CHART": (6, 6),
    "SERIES": (3, None),
}
# 1-based field indices that must parse as int / float.
INT_FIELDS = {
    "SLIDE": [1],
    "BULLET": [1],
    "SHAPE": [1],
    "BG": [1, 2, 3],
    "TABLE": [1, 2],
    "CELL": [1, 2],
    "CHART": [1],
}
FLOAT_FIELDS = {
    "TEXT": [1, 2, 3, 4],
    "IMAGE": [1, 2, 3, 4],
    "SHAPE": [2, 3, 4, 5],
    "TABLE": [3, 4, 5, 6],
    "CHART": [2, 3, 4, 5],
}
NEEDS_SLIDE = set(ARITY) - {"SLIDE"}


def validate_ops(text: str) -> list[str]:
    """Return a list of human-readable error strings (empty == valid)."""
    errors = []
    have_slide = have_table = have_chart = False
    chart_open_line = 0  # line of the current CHART, 0 == none open
    chart_has_series = False

    def close_chart():
        # A CHART with no SERIES keeps PowerPoint's default sample data.
        if chart_open_line and not chart_has_series:
            errors.append(
                f"line {chart_open_line}: CHART has no SERIES (the chart "
                "would keep PowerPoint's default sample data)"
            )

    for n, raw in enumerate(text.split("\n"), start=1):
        line = raw.rstrip("\r")
        if not line.strip():
            continue
        fields = line.split(US)
        op = fields[0].strip().upper()
        if op not in ARITY:
            errors.append(f"line {n}: unknown op {op!r}")
            continue
        lo, hi = ARITY[op]
        if len(fields) < lo or (hi is not None and len(fields) > hi):
            want = f"{lo}" if lo == hi else (f">={lo}" if hi is None else f"{lo}-{hi}")
            errors.append(f"line {n}: op {op} expects {want} fields, got {len(fields)}")
            continue
        for idx in INT_FIELDS.get(op, []):
            try:
                int(fields[idx])
            except ValueError:
                errors.append(
                    f"line {n}: op {op} field {idx} must be an integer, got {fields[idx]!r}"
                )
        for idx in FLOAT_FIELDS.get(op, []):
            try:
                float(fields[idx])
            except ValueError:
                errors.append(
                    f"line {n}: op {op} field {idx} must be a number, got {fields[idx]!r}"
                )
        if op == "SERIES":
            for idx in range(2, len(fields)):
                try:
                    float(fields[idx])
                except ValueError:
                    errors.append(
                        f"line {n}: SERIES value {idx} must be a number, got {fields[idx]!r}"
                    )
        if op == "BG":
            for idx in (1, 2, 3):
                try:
                    if not 0 <= int(fields[idx]) <= 255:
                        errors.append(
                            f"line {n}: BG channel {idx} must be 0-255, got {fields[idx]}"
                        )
                except ValueError:
                    pass  # already reported by INT_FIELDS
        # state rules
        if op == "SLIDE":
            try:
                if int(fields[1]) < 0:
                    errors.append(
                        f"line {n}: SLIDE layout index must be >= 0, got {fields[1]}"
                    )
            except (ValueError, IndexError):
                pass  # already reported by INT_FIELDS / arity
            close_chart()
            chart_open_line, chart_has_series = 0, False
            have_slide, have_table, have_chart = True, False, False
        elif op in NEEDS_SLIDE and not have_slide:
            errors.append(f"line {n}: {op} before any SLIDE")
        if op == "TABLE":
            have_table = True
        elif op == "CELL" and not have_table:
            errors.append(f"line {n}: CELL before any TABLE on the current slide")
        if op == "CHART":
            close_chart()
            have_chart = True
            chart_open_line, chart_has_series = n, False
        elif op in ("CAT", "SERIES") and not have_chart:
            errors.append(f"line {n}: {op} before any CHART on the current slide")
        if op == "SERIES":
            chart_has_series = True
    close_chart()
    return errors


def main() -> None:
    if len(sys.argv) != 2:
        print("usage: validate-deckops.py <ops-file>", file=sys.stderr)
        sys.exit(2)
    path = Path(sys.argv[1])
    try:
        text = path.read_text(encoding="utf-8")
    except FileNotFoundError:
        print(
            f"ERROR: ops file not found: {path} — emit it per "
            "references/deckops-spec.md.",
            file=sys.stderr,
        )
        sys.exit(1)
    except UnicodeDecodeError as e:
        print(
            f"ERROR: ops file {path} is not valid UTF-8 ({e}) — re-emit it as "
            "UTF-8 per references/deckops-spec.md.",
            file=sys.stderr,
        )
        sys.exit(1)
    except OSError as e:
        print(
            f"ERROR: cannot read ops file {path}: {e.strerror or e} — check the "
            "path and permissions.",
            file=sys.stderr,
        )
        sys.exit(1)
    errors = validate_ops(text)
    if errors:
        print("ERROR: invalid deck op sequence:", file=sys.stderr)
        for e in errors:
            print(f"  {e}", file=sys.stderr)
        sys.exit(1)
    slides = sum(
        1 for ln in text.split("\n") if ln.split(US)[0].strip().upper() == "SLIDE"
    )
    ops = sum(1 for ln in text.split("\n") if ln.strip())
    print(json.dumps({"slides": slides, "ops": ops}))


if __name__ == "__main__":
    main()