#!/usr/bin/env python3
"""final_qc.py — the checks nothing else runs, on the files a human actually receives.

WHY THIS IS A STAGE AND NOT A SCRATCHPAD SCRIPT. Every check here caught a real defect
on a delivered film, and the battery lived in a throwaway session script — if the agent
driving that session had not written it, the defects ship. The specific holes it covers:

  SHAPE      a 9:16 film shipped as a landscape crop of itself. deliver.py skips
             dimension checks entirely on the 1080p path; check_master compares only
             against the mv config (which was itself wrong). Nothing compared the
             DELIVERED pixels to what the PACK asked for.
  FRAME 0    it is the feed thumbnail; a black frame 0 is a scroll-past.
  LOUDNESS   nothing in the pipeline measured LUFS, ever. The birthday film shipped at
             -16.6. Measured on the ENCODED file — AAC overshoots a clean master.
  CAPTIONS   whisper hallucinated "Thank you for watching!" over a silent outro and it
             was BURNED INTO the delivered film. Caption text must come from the lyric
             sheet, so every cue is checked against it.
  FOREIGN    a review surface once mixed another project's videos in. Every file under
             final/ must carry this film's slug.
  SYNC       sync-gate no longer blocks unattended runs (that is what let films finish),
             which means its 80ms table scrolls past nobody. Quote it in the report.
  WHOLE FILM one frame per second, as a contact sheet, recorded SKIP — someone must
             look at it; a machine PASS would invite exactly the skim it exists to stop.

A check that cannot run is a SKIP, never a PASS (check_master.py's rule). Any FAIL is
exit 5 and the runner dies: `deliver` is not the last word, this is.

Usage:
  final_qc.py --project <dir> --slug <slug> --resolution 1080x1920 [--aspect 9:16]
              [--lyrics references/lyrics.txt] [--target-lufs -14] [--json]
"""
from __future__ import annotations

import argparse
import difflib
import glob
import json
import os
import re
import subprocess
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from rap_polish import measure as measure_loudness  # noqa: E402  (same ebur128 read)

FFMPEG = os.environ.get("FFMPEG_FULL", "/opt/homebrew/opt/ffmpeg-full/bin/ffmpeg")
BLACK_LUMA = 16.0          # BT.601 black is 16; a composed card sits far above it
LUFS_TOLERANCE = 1.0
MAX_TRUE_PEAK = -1.0


MIN_SHOT_S = 0.5           # two scene cuts closer than this are a flash frame
SCENE_THRESHOLD = 0.35     # ffmpeg scene score for a hard cut (a fade scores far lower)


def shortest_shot(path: str) -> tuple[float | None, float | None]:
    """(shortest gap between consecutive scene cuts, its start) via ffmpeg's scene
    detector; (None, None) when the pass cannot run. One decode of the file."""
    try:
        p = subprocess.run([FFMPEG, "-hide_banner", "-i", path, "-vf",
                            f"select='gt(scene,{SCENE_THRESHOLD})',showinfo", "-an", "-f", "null", "-"],
                           capture_output=True, text=True)
    except OSError:
        return None, None
    cuts = [float(m) for m in re.findall(r"pts_time:\s*([0-9.]+)", p.stderr)]
    if len(cuts) < 2:
        return None, None
    gaps = [(b - a, a) for a, b in zip(cuts, cuts[1:])]
    g, at = min(gaps)
    return round(g, 3), round(at, 3)


def probe(path: str) -> dict:
    r = subprocess.run(
        ["ffprobe", "-v", "error", "-select_streams", "v:0",
         "-show_entries", "stream=width,height", "-show_entries", "format=duration",
         "-of", "json", path], capture_output=True, text=True)
    try:
        d = json.loads(r.stdout)
        st = (d.get("streams") or [{}])[0]
        return {"w": int(st.get("width") or 0), "h": int(st.get("height") or 0),
                "duration": float(d.get("format", {}).get("duration") or 0)}
    except (ValueError, KeyError):
        return {"w": 0, "h": 0, "duration": 0.0}


def frame0_luma(path: str) -> float | None:
    r = subprocess.run(
        [FFMPEG, "-hide_banner", "-i", path, "-frames:v", "1",
         "-vf", "signalstats,metadata=print:key=lavfi.signalstats.YAVG",
         "-f", "null", "-"], capture_output=True, text=True)
    m = re.search(r"YAVG=([\d.]+)", r.stderr)
    return float(m.group(1)) if m else None


def contact_sheet(path: str, out: str, seconds: float) -> bool:
    cols = 10
    rows = max(1, (int(seconds) + cols - 1) // cols)
    r = subprocess.run(
        [FFMPEG, "-v", "error", "-y", "-i", path,
         "-vf", f"fps=1,scale=160:-1,tile={cols}x{rows}:margin=2:padding=2",
         "-frames:v", "1", out], capture_output=True, text=True)
    return r.returncode == 0 and os.path.isfile(out)


def caption_cues(ass_path: str) -> list[str]:
    cues = []
    for line in open(ass_path, encoding="utf-8"):
        if line.startswith("Dialogue:"):
            text = line.split(",", 9)[-1].strip()
            text = re.sub(r"\{[^}]*\}", "", text).replace("\\N", " ")
            if text:
                cues.append(text)
    return cues


def cue_in_sheet(cue: str, lines: list[str]) -> bool:
    """Fuzzy: whisper timings are trusted, the TEXT must be the sheet's. A cue that
    matches no lyric line at all is the hallucination class ("Thank you for
    watching!"), not a mishearing."""
    want = re.sub(r"[^a-z' ]", "", cue.lower()).strip()
    if not want:
        return True
    best = difflib.get_close_matches(want, lines, n=1, cutoff=0.6)
    if best:
        return True
    # a cue may span parts of two lines (balanced two-line splits) — try halves
    half = want.split()
    if len(half) >= 4:
        mid = len(half) // 2
        return bool(difflib.get_close_matches(" ".join(half[:mid]), lines, n=1, cutoff=0.6)
                    or difflib.get_close_matches(" ".join(half[mid:]), lines, n=1, cutoff=0.6))
    return False


HOUSE_FILES = ("VERSIONS.md", "thumbnail.png")


def is_foreign(name: str, slug: str) -> bool:
    """A file under final/ that is not this film's. The lane's own derived sheets are
    not foreign: `KNOWN-ISSUES-<style>.md` (the needs stage writes it next to the
    masters, and final_qc refused its own delivery over it — New Era dry run,
    2026-08-29)."""
    if slug in name or name in HOUSE_FILES:
        return False
    return not name.startswith("KNOWN-ISSUES-")


def pick_targets(project: str) -> tuple[list[str], list[str]]:
    """(targets, superseded). THE CURRENT VERSION IS JUDGED; A SUPERSEDED ONE IS NAMED.

    The YT masters under final/videos/film are versioned (-vN-YT.mp4), and a re-plan
    leaves the operator's fallback beside the new cut (v6 next to v7). Judging every
    file refused the RUN for the old master's 0.29 s flash frame — the very defect the
    re-plan existed to fix — while the new cut passed every check (Baby Ram & Sita,
    2026-09-02). Deliverables are unversioned and current by construction; among the
    YT masters the highest version is the film; the rest are reported, not judged."""
    deliverables = sorted(glob.glob(os.path.join(project, "final", "deliverables", "*.mp4")))
    yt = sorted(glob.glob(os.path.join(project, "final", "videos", "film", "*-YT.mp4")))

    def version(path: str) -> int:
        m = re.search(r"-v(\d+)-YT\.mp4$", os.path.basename(path))
        return int(m.group(1)) if m else -1

    current = max((version(p) for p in yt), default=-1)
    superseded = [p for p in yt if version(p) != current] if current >= 0 else []
    return deliverables + [p for p in yt if p not in superseded], superseded


def main() -> None:
    ap = argparse.ArgumentParser()
    ap.add_argument("--project", required=True)
    ap.add_argument("--slug", required=True)
    ap.add_argument("--resolution", required=True, help="what the PACK asked for, WxH")
    ap.add_argument("--aspect", default="")
    ap.add_argument("--lyrics", default="")
    ap.add_argument("--captions", default="", help="the .ass burned into the film")
    ap.add_argument("--target-lufs", type=float, default=-14.0)
    ap.add_argument("--json", action="store_true")
    args = ap.parse_args()

    P = args.project
    try:
        want_w, want_h = (int(x) for x in args.resolution.lower().split("x"))
    except ValueError:
        print(f"final_qc: --resolution {args.resolution!r} is not WxH", file=sys.stderr)
        raise SystemExit(2)

    # The files a human receives: deliverables, plus the normalised master they came from.
    targets, superseded = pick_targets(P)
    if not targets:
        print("final_qc: nothing under final/deliverables or final/videos/film/*-YT — "
              "run deliver first", file=sys.stderr)
        raise SystemExit(2)

    checks: list[dict] = []

    def record(name: str, ok: bool, detail: str, skipped: bool = False) -> None:
        # A CHECK THAT DID NOT RUN IS NOT A PASS. Eight of New Era's 31 checks were
        # recorded both skipped and ok, so "failures: 0" counted contact sheets nobody
        # had opened (results review, 2026-09-02). Skipped = ok None: neither.
        checks.append({"check": name, "ok": (None if skipped else bool(ok)), "detail": detail, "skipped": skipped})

    if superseded:
        # named, never refused: the operator archives a fallback on his own word
        record("superseded-in-final", True,
               f"{len(superseded)} superseded master(s) still under final/videos/film — not judged; "
               f"archive when the new cut is approved: " + ", ".join(os.path.basename(f) for f in superseded),
               skipped=True)

    # 6. FOREIGN CONTENT — once, over the whole tree.
    foreign = [f for f in glob.glob(os.path.join(P, "final", "**", "*"), recursive=True)
               if os.path.isfile(f) and is_foreign(os.path.basename(f), args.slug)]
    record("no-foreign-content", not foreign,
           "every file under final/ carries this film's slug" if not foreign else
           f"{len(foreign)} file(s) do not belong to {args.slug}: "
           + ", ".join(os.path.basename(f) for f in foreign[:5]))

    lyric_lines = []
    if args.lyrics and os.path.isfile(args.lyrics):
        lyric_lines = [re.sub(r"[^a-z' ]", "", l.lower()).strip()
                       for l in open(args.lyrics, encoding="utf-8")
                       if l.strip() and not l.strip().startswith("[")]

    for f in targets:
        base = os.path.basename(f)
        info = probe(f)

        # 1. SHAPE at the pixels vs the pack. Deliverables may legitimately be an
        # integer upscale of the requested resolution (720x1280 -> 1080x1920 -> 4K),
        # so the assertion is the ASPECT and never-smaller, with portrait/landscape
        # orientation exact.
        same_orientation = (info["w"] < info["h"]) == (want_w < want_h)
        aspect_ok = abs((info["w"] / max(1, info["h"])) - (want_w / want_h)) < 0.02
        record(f"shape:{base}", same_orientation and aspect_ok,
               f"{info['w']}x{info['h']} vs pack {want_w}x{want_h}"
               + ("" if same_orientation and aspect_ok else
                  " — the film is the WRONG SHAPE; a crop has happened somewhere and "
                  "no duration check can see it"))

        # 2. FRAME 0.
        luma = frame0_luma(f)
        record(f"frame0:{base}", luma is not None and luma > BLACK_LUMA,
               f"mean luma {luma:.1f}" if luma is not None else "unmeasurable"
               + ("" if luma and luma > BLACK_LUMA else
                  " — frame 0 is the feed thumbnail and it is black"))

        # 3b. NO FLASH FRAMES. A performer sliver of seven frames between a cutaway and
        # the next cut read as "goes funny and quickly goes to Sita" (film #2 v6, 0:59;
        # the results review's shot-length pass found exactly that one shot across seven
        # films). Scene cuts closer together than MIN_SHOT_S are a flash frame.
        shortest, at = shortest_shot(f)
        if shortest is None:
            record(f"shots:{base}", True, "scene cuts unmeasurable", skipped=True)
        else:
            record(f"shots:{base}", shortest >= MIN_SHOT_S,
                   f"shortest shot {shortest:.2f}s" + ("" if shortest >= MIN_SHOT_S else
                   f" at {at:.2f}s — a flash frame between two cuts (min {MIN_SHOT_S:g}s)"))

        # 4. LOUDNESS on the encoded file.
        lufs, tp = measure_loudness(f)
        if lufs is None:
            record(f"loudness:{base}", False, "no measurable audio")
        else:
            ok = (abs(lufs - args.target_lufs) <= LUFS_TOLERANCE
                  and (tp is None or tp <= MAX_TRUE_PEAK))
            record(f"loudness:{base}", ok,
                   f"{lufs:.1f} LUFS, peak {tp if tp is not None else '?'} dBTP "
                   f"(target {args.target_lufs:g}±{LUFS_TOLERANCE:g}, peak ≤ {MAX_TRUE_PEAK:g})"
                   + ("" if ok else " — run the polish stage"))

        # 3. WHOLE FILM, one frame a second — SKIP by design, someone must look.
        sheet = os.path.join(P, "build", f"qc-sheet-{os.path.splitext(base)[0]}.jpg")
        made = contact_sheet(f, sheet, info["duration"])
        record(f"contact-sheet:{base}", made,
               f"NOT RUN — {sheet if made else 'sheet generation failed'} — "
               "SOMEONE MUST LOOK AT IT", skipped=made)

    # 5. CAPTION TEXT ⊆ LYRIC SHEET.
    if args.captions and os.path.isfile(args.captions) and lyric_lines:
        phantoms = [c for c in caption_cues(args.captions)
                    if not cue_in_sheet(c, lyric_lines)]
        record("captions-from-sheet", not phantoms,
               f"all cues trace to the lyric sheet" if not phantoms else
               f"{len(phantoms)} cue(s) match NO lyric line — the hallucination class "
               f"that burned 'Thank you for watching!' into a delivered film: "
               + " | ".join(phantoms[:3]))
    else:
        record("captions-from-sheet", True,
               "NOT RUN — no captions file or no lyric sheet given", skipped=True)

    # 7. THE SYNC TABLE a human should see.
    profiles = sorted(glob.glob(os.path.join(P, "build", "sync-profile-*.json")))
    if profiles:
        rows = []
        for pf in profiles[:1]:
            doc = json.load(open(pf, encoding="utf-8"))
            for r in (doc if isinstance(doc, list) else doc.get("windows") or []):
                rows.append(r)
        record("sync-profile-quoted", True,
               f"NOT RUN — advisory. {os.path.basename(profiles[0])}: "
               + "; ".join(f"{r.get('window', r.get('clip', '?'))}="
                           f"{r.get('offsetMs', r.get('offset_ms', '?'))}ms"
                           for r in rows[:10]), skipped=True)
    else:
        record("sync-profile-quoted", True,
               "NOT RUN — no sync-profile json found; sync was never profiled",
               skipped=True)

    failures = [c for c in checks if c["ok"] is False]
    report = {"slug": args.slug, "targets": [os.path.basename(t) for t in targets],
              "checks": checks, "failures": len(failures)}
    json.dump(report, open(os.path.join(P, "build", "qc-report.json"), "w",
                           encoding="utf-8"), indent=1)

    for c in checks:
        tag = "SKIP" if c["skipped"] else ("PASS" if c["ok"] else "FAIL")
        print(f"  {tag}  {c['check']}: {c['detail']}")
    if args.json:
        print(json.dumps(report, indent=2))
    if failures:
        print(f"final_qc: FAILED ({len(failures)}) — the delivered files are not "
              f"ready to hand to anyone", file=sys.stderr)
        raise SystemExit(5)
    skipped = [c["check"] for c in checks if c["skipped"]]
    print(f"final_qc: PASS ({len(skipped)} check(s) NOT RUN: they end in a picture — "
          f"open them)", file=sys.stderr)


if __name__ == "__main__":
    main()
