"""Shared helpers for all validators in /root/.claude/hooks/validators/."""
import json
import sys
from pathlib import Path
from typing import Any


def emit_report(name: str, ok: bool, errors: list[str], details: dict[str, Any] | None = None) -> int:
    """Write a JSON report to stdout in the agreed schema, return exit code."""
    report = {
        "validator": name,
        "status": "pass" if ok else "fail",
        "errors": errors,
        "details": details or {},
    }
    if ok:
        print(json.dumps(report, ensure_ascii=False))
    else:
        # On fail: write a 'Resolve this' instruction-block so a calling agent self-heals.
        sys.stderr.write(json.dumps(report, ensure_ascii=False, indent=2))
        sys.stderr.write("\n\n")
        sys.stderr.write(f"Resolve these {len(errors)} validator-errors before proceeding:\n")
        for i, e in enumerate(errors, 1):
            sys.stderr.write(f"  {i}. {e}\n")
    return 0 if ok else 2


def read_input(path_arg: str | None) -> str:
    """Read from file path or stdin (when path_arg is '-' or None)."""
    if path_arg and path_arg != "-":
        return Path(path_arg).read_text(encoding="utf-8")
    return sys.stdin.read()