#!/usr/bin/env python3
"""needs_report.py — one verdict per window: what it needs, why, and the exact next command.

WHY THIS EXISTS. After Smooth Like That the four questions the operator asked — is it on
the bar, does it need a slide, where does it need a cover, must it be re-rendered and
with what change — each had an answer somewhere on disk: the driver's live-job verdicts,
the slide report, the library's fit table, the salvage spans, the sync profile, the
word-sync verdicts, the cutaway record. Nothing joined them, so every fix was decided by
a person reading five files, and the film went out four times.

This joins them. Every input is optional — a missing artifact reads as "n/a", never as an
error — so it runs BEFORE the cut (from the render records, the slide and the library) and
AGAIN after the sync gate (in film time, from the profile and the word-sync verdicts),
when it also writes the KNOWN-ISSUES file that ships with the delivery.

One token per window, by precedence:
    reuse:<clipId>      a clip the project already owns fits this window (library fit table)
                        — free, so it beats a re-render
    rerender:<change>   nothing free fixes it; <change> is what the second attempt MUST
                        change (scrub = the set clause; resplit = the window; redraw =
                        the draw budget, RAP_DRAWS=3, the operator's call; draw = never landed)
    cover:<a-b[,a-b]>   cut away over these SONG seconds (mouthing, wander tail, held frame)
    slide               a steady offset; sync_shift moves it for free
    ok                  on the bar, or exempt/accepted by ear
"""
from __future__ import annotations

import argparse
import html
import json
import os
import re
import sys
import os as _os, sys as _sys
_sys.path.insert(0, _os.path.dirname(_os.path.abspath(__file__)))
from lane_page import page as shell, pill  # noqa: E402

TOKEN_RANK = {"reuse": 0, "rerender": 1, "cover": 2, "slide": 3, "ok": 4, "verify": 3}   # a free reuse beats a 30-min draw


def load(path: str | None):
    if not path or not os.path.isfile(path):
        return None
    try:
        return json.load(open(path, encoding="utf-8"))
    except (OSError, ValueError):
        return None


def mmss(t: float) -> str:
    t = max(0.0, float(t))
    return f"{int(t // 60)}:{t % 60:04.1f}"


WORDS_MIN = 90   # vocal-swap: a take heard below this share of its words is a words defect


def rank(token: str) -> int:
    return TOKEN_RANK.get(token.split(":")[0], 9)


def _win_no(x) -> int:
    """A window number from either spelling: index_library writes the plan job id
    ("w03"), the plan itself carries the integer. int("w00") crashed the synthetic
    dry run of the New Era film (2026-08-29) before a slot was spent."""
    if isinstance(x, int):
        return x
    t = str(x).strip().lower()
    return int(t[1:]) if t.startswith("w") else int(t)


def assess(plan: dict, *, broll_plan=None, library=None, shift=None, vocal_map=None, salvage=None,
           profile=None, word_sync=None, cutaways=None, rate=None, swap=None, queue_dir: str = "", broll_dir: str = "",
           audio_mode: str = "record") -> list[dict]:
    """The join. Returns one row per performance window (plan order).

    audio_mode="vocal-swap" (AUDIO_MODE in the pack): the film's audio is the record's
    beat + each take's OWN voice where it plays (vocal_swap.py), so every verdict about
    the take's timing against the record — driver rhythm/rate shapes, slide, rate-fit,
    salvage, sync-gate, word-sync, reuse fits — is moot and is not a defect. What still
    is: a take that never landed, and a take that dropped WORDS (the driver heard fewer
    than WORDS_MIN of the line's words), because under vocal-swap the take's words are
    the film's words."""
    swap_mismatch: dict[str, list] = {}
    swap_edges: dict[str, list] = {}
    for vm in (swap or {}).get("voiceMismatch") or []:
        swap_mismatch.setdefault(str(vm.get("window")), []).append(vm)
    for ew in (swap or {}).get("edgeWords") or []:
        swap_edges.setdefault(str(ew.get("window")), []).append(ew)
    live = {}
    if queue_dir and os.path.isdir(queue_dir):
        for j in plan.get("jobs", []):
            live[j["id"]] = load(os.path.join(queue_dir, f"{j['id']}-live-job.json")) or {}
    shift_rows = {r.get("clip"): r for r in ((shift or {}).get("shifted") or [])}
    rate_rows = {r.get("clip"): r for r in ((rate or {}).get("windows") or [])}
    shift_rerender = {r.get("clip"): r for r in ((shift or {}).get("needsRerender") or [])}
    prof_rows = {r.get("clip"): r for r in ((profile or {}).get("windows") or [])}
    ws_rows = {r.get("clip"): r for r in ((word_sync or {}).get("windows") or [])}
    cut_rows: dict[str, list] = {}
    for c in ((cutaways or {}).get("cutaways") or []):
        cut_rows.setdefault(c.get("clip"), []).append(c)
    salv = ((salvage or {}).get("windows") or {})
    gaps = [(float(g["start"]), float(g["end"])) for g in ((vocal_map or {}).get("shortGaps") or [])]
    fits_by_window: dict[int, list] = {}
    for c in ((library or {}).get("clips") or []):
        for f in c.get("fits") or []:
            if f.get("usable") and f.get("faceOk") is not False:
                fits_by_window.setdefault(_win_no(f["window"]), []).append((c["id"], c.get("clip"), f))
    broll_by_style = {}
    for b in ((broll_plan or {}).get("jobs") or []):
        broll_by_style.setdefault(b.get("styleId"), b)

    rows = []
    for j in plan.get("jobs", []):
        jid, idx = j["id"], int(j.get("window", 0))
        start, secs = float(j.get("startSec") or 0), float(j.get("seconds") or 0)
        end = start + secs
        voiced = bool(j.get("voiceRef")) and j.get("synced") is not False
        rec = live.get(jid, {})
        on_disk = bool(queue_dir) and os.path.isfile(os.path.join(queue_dir, "clips", f"{jid}.mp4"))
        cands: list[tuple[str, str]] = []          # (token, evidence)

        if not voiced:
            cands.append(("ok", "instrumental window — no voice to sync (exempt)"))
        if queue_dir and not on_disk:
            cands.append(("rerender:draw", "no clip on disk — never landed"
                          + (f" (last: {rec.get('needs')})" if rec.get("needs") else "")))
        if rec.get("needs") and rec.get("needs") not in ("ok",) and on_disk:
            cands.append((rec["needs"], f"driver: {rec.get('verdict') or rec.get('shape') or rec['needs']}"
                          + (f" [{rec['variant']} variant]" if rec.get("variant") else "")))
        elif rec.get("needs") == "ok":
            cands.append(("ok", f"driver: {rec.get('verdict') or 'on the bar'}"))
        rr = rate_rows.get(jid)
        if rr and rr.get("action") == "retimed":
            cands.append(("ok", f"rate-fit: retimed x{1 / float(rr['rate']):.3f} ({rr.get('why')})"))
        elif rr and rr.get("residualMs") is not None and rr.get("residualMs") > 200 and rr.get("action") == "left":
            cands.append(("cover:" + f"{start:.2f}-{end:.2f}", f"rate-fit: {rr.get('why')}"))
        sr = shift_rows.get(jid)
        if sr:
            held = sr.get("heldMs") or 0
            cands.append((("cover:" + f"{start:.2f}-{start + held / 1000:.2f}") if held > 0 else "slide",
                          f"slide: {sr.get('beforeMs'):+d}ms -> {sr.get('afterMs'):+d}ms"
                          + (f", {held}ms held frame at the head" if held > 0 else "")))
        if jid in shift_rerender:
            r = shift_rerender[jid]
            cands.append(("rerender:resplit", f"slide could not fix it ({r.get('offsetMs'):+d}ms) — wanders"))
        for lo, hi in salv.get(jid, []):
            cands.append((f"cover:{float(lo):.2f}-{float(hi):.2f}", "salvage: the tail drifts off the bar"))
        for lo, hi in gaps:
            if lo < end and hi > start and voiced:
                cands.append((f"cover:{max(lo, start):.2f}-{min(hi, end):.2f}", "vocal map: short gap — mouthing risk"))
        pr = prof_rows.get(jid)
        if pr:
            v = str(pr.get("verdict") or "")
            if v.startswith("ok") or v.startswith("ACCEPTED") or v == "EXEMPT":
                cands.append(("ok", f"sync-gate: {v}" + (f" ({pr.get('offsetMs'):+d}ms)" if isinstance(pr.get("offsetMs"), int) else "")))
            elif v in ("MARGINAL", "OFF-BAR"):
                cands.append(("slide", f"sync-gate: {v} {pr.get('offsetMs'):+d}ms — {pr.get('action')}"))
            elif v == "WANDERS":
                cands.append(("rerender:resplit", f"sync-gate: WANDERS (spread {pr.get('spreadMs')}ms) — {pr.get('action')}"))
            elif v == "UNMEASURABLE":
                cands.append(("rerender:redraw", "sync-gate: UNMEASURABLE — no readable vocal correlation"))
            for m in pr.get("mouthingAt") or []:
                try:
                    a, b = float(m[0]), float(m[1])
                    cands.append((f"cover:{a:.2f}-{b:.2f}", "sync-gate: mouthing over no vocal"))
                except (TypeError, ValueError, IndexError):
                    pass
        wr = ws_rows.get(jid)
        if wr:
            v = str(wr.get("verdict") or "")
            if v in ("RE-RENDER", "WRONG-LYRIC", "NO-TRANSCRIPT"):
                cands.append(("rerender:redraw", f"word-sync: {v} — {wr.get('note') or ''}".rstrip(" —")))
            elif v == "SLIDE":
                cands.append(("slide", f"word-sync: SLIDE {wr.get('driftMs'):+d}ms"))
            elif v == "OK":
                cands.append(("ok", "word-sync: OK"))
        covered = cut_rows.get(jid, [])
        evidence_extra = [f"covered {c['startSec']:.1f}-{c['endSec']:.1f}s with {c.get('broll')} ({c.get('why') or 'cutaway'})"
                          for c in covered]
        # a cover already applied answers a cover candidate for the same span
        if covered:
            cands = [(t, e) for t, e in cands if not (t.startswith("cover:") and any(
                abs(float(t.split(":")[1].split("-")[0]) - c["startSec"]) < 0.3 for c in covered))]
        if not cands:
            cands.append(("ok", "no measurement says otherwise" if on_disk or not queue_dir else "n/a"))
        # reuse beats a re-render when the library already fits this window
        if any(t.startswith("rerender") for t, _ in cands) and fits_by_window.get(idx):
            cid, cpath, f = sorted(fits_by_window[idx], key=lambda x: -float(x[2].get("corr") or 0))[0]
            cands.append((f"reuse:{cid}", f"library: {cid} fits this window (corr {f.get('corr')} @ {f.get('offsetMs'):+d}ms) — {cpath}"))
        if audio_mode == "vocal-swap" and voiced:
            kept = [(t, e) for t, e in cands if t == "rerender:draw"]
            verdict = str(rec.get("verdict") or "")
            m = re.search(r"\((\d+)% of the words\)", verdict)
            if m and int(m.group(1)) < WORDS_MIN:
                kept.append(("verify:words", f"driver heard {m.group(1)}% of the words — under vocal-swap the take's "
                                             f"words ARE the film's; check this window by ear"))
            if not kept:
                kept.append(("ok", "vocal-swap: the take's own voice plays with its mouth; its timing against the record is moot"))
            cands = kept
        # WHAT THE SWAP FOUND reaches the page, not only the log (film3 item 12): a take
        # whose voice the swap refused (the record's vocal plays there) and a take word
        # sitting on a segment's edge (half-faded) are the operator's ear to settle.
        for vm in swap_mismatch.get(jid, []):
            tk, rc = vm.get("take") or {}, vm.get("record") or {}
            cands.append(("verify:voice", f"swap: the take's voice sits at {tk.get('median', 0):.0f} Hz "
                                          f"({tk.get('lowShare', 0):.0%} low) against the record's {rc.get('median', 0):.0f} Hz "
                                          f"({rc.get('lowShare', 0):.0%}) — the record's vocal was kept; check by ear"))
        for ew in swap_edges.get(jid, []):
            cands.append(("verify:edge", f"swap: the word {ew.get('word')!r} at {ew.get('at', 0):.2f}s sits on the segment's "
                                         f"{ew.get('edge')} ({ew.get('edgeAt', 0):.2f}s) — half-faded; move the cut or the span"))
        cands.sort(key=lambda te: rank(te[0]))
        token = cands[0][0]
        # several cover spans merge into one token
        if token.startswith("cover:"):
            spans = sorted({t.split(":", 1)[1] for t, _ in cands if t.startswith("cover:")})
            token = "cover:" + ",".join(spans)
        rows.append({"id": jid, "window": idx, "styleId": j.get("styleId"), "startSec": start, "seconds": secs,
                     "film": mmss(start), "voiced": voiced, "onDisk": on_disk, "token": token,
                     "evidence": [e for _, e in cands] + evidence_extra,
                     "deferredBroll": (broll_by_style.get(j.get("styleId")) or {}).get("id")
                     if (broll_by_style.get(j.get("styleId")) or {}).get("deferred") and token.startswith("cover:")
                     and broll_dir and not os.path.isfile(os.path.join(broll_dir, f"{broll_by_style[j.get('styleId')]['id']}.mp4"))
                     else None})
    return rows


def next_command(row: dict, pack: str, slug: str, scripts: str, project: str) -> str:
    run = f"make-rap-mv.sh {pack} {slug}"
    t, jid = row["token"], row["id"]
    kind = t.split(":")[0]
    if kind == "ok":
        return "—"
    if kind == "slide":
        return f"{run} --from slide"
    if kind == "verify":
        return f"listen to {jid} on the review board; if a word is missing: {run} --replace {jid}"
    if kind == "cover":
        spans = ",".join(f"{jid}:{s}" for s in t.split(":", 1)[1].split(","))
        pre = (f"python3 {scripts}/lane_render.py --plan {project}/build/broll-plan.json --only {row['deferredBroll']}  &&  "
               if row.get("deferredBroll") else "")
        return f'{pre}COVER_SPANS="{spans}" {run} --from cover'
    if kind == "reuse":
        return f'REUSE_FORCE="{jid}=<path from the evidence>" {run} --from inventory'
    change = t.split(":", 1)[1] if ":" in t else "redraw"
    hint = {"scrub": f"set `setAlt` on style {row.get('styleId')} in the styles file, then",
            "resplit": f"pin/re-split the window (LINE_WINDOW_PINS or WINDOW_LINES=1), then",
            "redraw": "RAP_DRAWS=3 (your call — a third draw of the same prompt) then",
            "draw": ""}.get(change, "")
    tail = f"{run} --from render-all" if change == "draw" else f"{run} --replace {jid}"
    return f"{hint} {tail}".strip()


def write_html(path: str, rows: list[dict], style: str, title: str) -> None:
    def cls(t: str) -> str:
        return {"ok": "ok", "slide": "slide", "cover": "cover", "reuse": "reuse"}.get(t.split(":")[0], "bad")
    body = "\n".join(
        f'<tr class="{cls(r["token"])}"><td>{html.escape(r["id"])}</td><td>{r["film"]}</td>'
        f'<td>{html.escape(str(r.get("styleId") or ""))}</td>'
        f'<td>{pill("PASS" if r["token"] == "ok" else "ADVISORY" if r["token"].startswith("verify") else "FAIL", r["token"])}</td>'
        f'<td>{"<br>".join(html.escape(e) for e in r["evidence"])}</td>'
        f'<td><code>{html.escape(r["next"])}</code></td></tr>' for r in rows)
    counts = {}
    for r in rows:
        counts[r["token"].split(":")[0]] = counts.get(r["token"].split(":")[0], 0) + 1
    summary = " · ".join(f"{k} {v}" for k, v in sorted(counts.items(), key=lambda kv: rank(kv[0])))
    doc = shell(f"NEEDS — {html.escape(style)}",
                f"{summary}. One token per window, by precedence <i>reuse &gt; rerender &gt; cover &gt; slide &gt; ok</i> "
                f"(a free reuse beats a draw); do the free ones first (slide), then covers, then reuse, and only then a "
                f"re-render with the named change.",
                f"<table><tr><th>window</th><th>film time</th><th>world</th><th>needs</th><th>evidence</th><th>next</th></tr>{body}</table>",
                extra_css="code{white-space:pre-wrap}tr.ok td b{color:var(--good)}tr.slide td b{color:#e0c65a}"
                          "tr.cover td b{color:#6bbfd8}tr.reuse td b{color:#c9a0d8}tr.bad td b{color:var(--danger)}")
    with open(path, "w", encoding="utf-8") as fh:
        fh.write(doc)
    try:
        from lane_nav import inject_nav
        inject_nav(path)
    except Exception:  # noqa: BLE001 — the menu is a courtesy
        pass


def write_known_issues(path: str, rows: list[dict], style: str, master: str) -> int:
    open_rows = [r for r in rows if not r["token"].startswith("ok")]
    lines = [f"# KNOWN ISSUES — {style} — {os.path.basename(master) if master else 'master'}", "",
             "Derived by needs_report.py from the sync gate, the word-sync verdicts, the cutaway record and the",
             "render records — never hand-typed. One row per window that is not clean.", "",
             "| song time | window | defect (plain words) | what was done | fix on offer | cost | ship / fix in v2 |",
             "|---|---|---|---|---|---|---|"]
    for r in open_rows:
        kind = r["token"].split(":")[0]
        done = "; ".join(e for e in r["evidence"] if e.startswith("covered") or e.startswith("slide:")) or "—"
        defect = "; ".join(e for e in r["evidence"] if not (e.startswith("covered") or e.startswith("slide:")))[:160] or r["token"]
        cost = {"slide": "free, minutes", "cover": "free, minutes (a cutaway may need ~30 min on the lane)",
                "reuse": "free, minutes", "rerender": "~30 min per draw on the single slot"}.get(kind, "—")
        lines.append(f"| {r['film']} | {r['id']} | {defect} | {done} | `{r['next']}` | {cost} |  |")
    if not open_rows:
        lines.append("| — | — | nothing open — every window is on the bar, exempt, or accepted by ear | | | |  |")
    with open(path, "w", encoding="utf-8") as fh:
        fh.write("\n".join(lines) + "\n")
    return len(open_rows)


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--project", required=True)
    ap.add_argument("--slug", required=True)
    ap.add_argument("--style", required=True)
    ap.add_argument("--pack", default="<pack>")
    ap.add_argument("--plan", required=True)
    for opt in ("broll-plan", "library", "shift-report", "rate-report", "vocal-map", "salvage", "profile", "word-sync",
                "cutaways", "known-issues", "master", "swap"):
        ap.add_argument(f"--{opt}", default="")
    ap.add_argument("--out", required=True)
    ap.add_argument("--json-out", required=True)
    ap.add_argument("--audio-mode", default="record", choices=("record", "vocal-swap"),
                    help="AUDIO_MODE from the pack; vocal-swap makes the record-timing verdicts moot")
    a = ap.parse_args()
    plan = load(a.plan)
    if not plan:
        print(f"needs_report: no plan at {a.plan}", file=sys.stderr)
        return 2
    scripts = os.path.dirname(os.path.abspath(__file__))
    rows = assess(plan, broll_plan=load(a.broll_plan), library=load(a.library), shift=load(a.shift_report),
                  vocal_map=load(a.vocal_map), salvage=load(a.salvage), profile=load(a.profile),
                  word_sync=load(a.word_sync), cutaways=load(a.cutaways), rate=load(a.rate_report), swap=load(a.swap),
                  queue_dir=plan.get("queueDir") or "", broll_dir=os.path.join(a.project, "build", "broll", "clips"),
                  audio_mode=a.audio_mode)
    for r in rows:
        r["next"] = next_command(r, a.pack, a.slug, scripts, a.project)
    deferred = sorted({r["deferredBroll"] for r in rows if r.get("deferredBroll")})
    doc = {"schemaVersion": 1, "style": a.style, "windows": rows, "deferredAsks": deferred,
           "inputs": {k: bool(getattr(a, k.replace("-", "_"))) for k in
                      ("broll-plan", "library", "shift-report", "vocal-map", "salvage", "profile", "word-sync", "cutaways")}}
    with open(a.json_out, "w", encoding="utf-8") as fh:
        json.dump(doc, fh, indent=1)
    write_html(a.out, rows, a.style, f"NEEDS — {a.slug} — {a.style}")
    n_open = 0
    if a.known_issues:
        n_open = write_known_issues(a.known_issues, rows, a.style, a.master)
        doc["knownIssues"] = {"path": a.known_issues, "open": n_open}
        with open(a.json_out, "w", encoding="utf-8") as fh:
            json.dump(doc, fh, indent=1)
    for r in rows:
        print(f"  {r['id']:<6} {r['film']:>7}  {r['token']:<22} {r['evidence'][0][:80] if r['evidence'] else ''}")
    print(f"needs_report: {a.out}" + (f" · deferred cutaways to render first: {', '.join(deferred)}" if deferred else "")
          + (f" · KNOWN-ISSUES: {n_open} open -> {a.known_issues}" if a.known_issues else ""))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
