Skip to content

Official Codebase of 3DCodeVerse

Python
18.3 KB
Raw Blame
"""Scene probes: the import/census gate and the shader-preflight report reader."""

from __future__ import annotations

import time
from collections.abc import Mapping
from pathlib import Path
from typing import Any

from pydantic import BaseModel, Field

from codeverse3d.config import get_settings
from codeverse3d.contracts.artifacts import GateFinding, GateReport, Severity
from codeverse3d.contracts.common import ENTRY_FILE, Language
from codeverse3d.conventions import DRAWS_WARN_SCENE, MAX_DRAWS_SCENE, MAX_TRIS_SCENE
from codeverse3d.spatial.render_scene import SceneRenderError, probe_env_args, run_scene_script
from codeverse3d.workspace import Workspace

PROBE_GATE = "scene_probe"
SHADER_GATE = "shader_preflight"

_BOOT_HINTS = {
    "import": "src/scene.js failed to import: fix the syntax/import error quoted above (imports must be 'three', 'three/addons/*' or relative paths that exist)",
    "createScene": "createScene({THREE, renderer, loaders}) threw or returned the wrong shape; it must return {scene: THREE.Scene, cameras: [...], update(t, dt)}",
    "loads": "an asset failed to load; check the '/assets/<name>.glb' path exists under public/assets",
    "first_update": "update(0, 0) threw; guard against undefined handles before animating",
}


class SceneProbeResult(BaseModel):
    """``probe_scene`` result."""

    gate: GateReport
    census: dict[str, Any] = Field(default_factory=dict)
    errors: list[str] = Field(default_factory=list, description="harness/driver failures only (tool could not run)")
    findings: list[str] = Field(default_factory=list, description="agent-fixable gate findings, one line each")
    ok: bool = False

    def __iter__(self):  # type: ignore[override]
        yield self.gate
        yield self.census


def probe_result(gate: GateReport, census: dict[str, Any]) -> SceneProbeResult:
    """A ``harness_failure`` finding IS a driver failure, wherever it was raised."""
    errors = [f.message[:800] for f in gate.findings if f.data.get("harness_failure")]
    lines = [f"[{f.severity.value}] {f.target or ''}: {f.message}" for f in gate.findings
             if f.severity != Severity.INFO and not f.data.get("harness_failure")]
    return SceneProbeResult(gate=gate, census=census, ok=not errors, errors=errors, findings=lines)


def _f(gate: str, sev: Severity, msg: str, *, target: str | None = None, hint: str = "", **data: Any) -> GateFinding:
    return GateFinding(gate=gate, severity=sev, target=target, message=msg, fix_hint=hint, data=data)


def run_probe(ws: Workspace, *, compile: bool = False, timeout_s: float | None = None,
              glb: Path | None = None, facts: Mapping[str, Any] | None = None,
              ) -> tuple[GateReport, GateReport, dict[str, Any]]:
    """One ``probe_scene.mjs`` boot → (scene_probe, shader_preflight, census)."""
    t0 = time.time()
    timeout_s = min(float(timeout_s or get_settings().limits.build_timeout_s), 120.0)
    args = ["--ws", str(ws.root), "--out", str(ws.artifacts / "scene_probe.json"), "--timeout-ms", str(int(timeout_s * 1000))]
    if compile:
        args += ["--compile", "--shaders-out", str(ws.artifacts / "shader_preflight.json")]
    if glb is not None:
        args += ["--glb", str(Path(glb).resolve()), "--no-settle"]
    else:
        args += probe_env_args()
    no_preflight = GateReport(gate=SHADER_GATE, passed=False, findings=[])
    try:
        res = run_scene_script("probe_scene.mjs", args, timeout_s=timeout_s + 20)
    except SceneRenderError as e:
        if e.scene_timed_out and glb is None:
            finding = timeout_finding(timeout_s, phase=e.phase)   # after run_scene_script's one retry
        else:
            finding = _f(PROBE_GATE, Severity.ERROR, f"scene probe could not run: {e}"[:1500], target="src/scene.js",
                         hint="this is a harness/driver failure, not your code; retry or report", harness_failure=True)
        return GateReport.of(PROBE_GATE, [finding], duration_ms=int((time.time() - t0) * 1000)), no_preflight, {}
    if glb is not None:
        probe, census = offline_report(res.summary, facts or {}, duration_ms=int((time.time() - t0) * 1000))
        return probe, no_preflight, census
    probe, census = probe_report(res.summary, duration_ms=int((time.time() - t0) * 1000))
    rep = res.summary.get("shader_report") or {}
    if not compile or not rep or rep.get("skipped"):
        return probe, no_preflight, census
    return probe, shader_report(rep, duration_ms=int(rep.get("duration_ms") or 0)), census


def timeout_finding(timeout_s: float, *, phase: str) -> GateFinding:
    """A probe whose watchdog fired inside the scene's own code (``render_scene.SCENE_PHASES``) —
    after the driver's one retry, on a browser of its own — is an ERROR against the CODE."""
    entry = ENTRY_FILE[Language.SCENE_THREEJS]
    what = {"scene": f"importing {entry} and createScene()", "census": "the census of what createScene() built",
            "update": "update(t, dt)"}.get(phase, "the scene's boot")
    return _f(PROBE_GATE, Severity.ERROR,
              f"scene construction exceeded the {timeout_s:.0f} s probe budget: {what} did not finish",
              target=entry, kind="probe_timeout", timed_out=True, phase=phase,
              hint=f"the scene must boot inside {timeout_s:.0f} s; the time is the scene's own construction work "
                   "(module-level code, createScene, update) — find what grows with the scene's size and bound it")


def probe_scene(ws: Workspace, *, timeout_s: float | None = None) -> SceneProbeResult:
    """Import-only probe."""
    report, _, census = run_probe(ws, timeout_s=timeout_s)
    if census:
        ws.write_json(ws.artifacts / "census.json", census)
    return probe_result(report, census)


def probe_report(summary: dict[str, Any], *, duration_ms: int = 0) -> tuple[GateReport, dict[str, Any]]:
    """Interpret a ``probe_scene.mjs`` summary into the ``scene_probe`` GateReport (+ census)."""
    gate = PROBE_GATE
    findings: list[GateFinding] = []
    s = summary
    boot = s.get("boot") or {}
    if "boot" not in s:
        findings.append(_f(gate, Severity.ERROR, "scene probe produced no result (driver output lost)",
                           target="src/scene.js",
                           hint="this is a harness/driver failure, not your code; retry or report",
                           harness_failure=True))
        return GateReport.of(gate, findings, duration_ms=duration_ms), {}
    if not boot.get("ok"):
        stage = boot.get("stage", "?")
        msg = boot.get("error") or "scene did not boot"
        if "Failed to fetch dynamically imported module" in msg:
            missing = [e for e in s.get("console_errors", []) if "404 not found" in e or "request failed" in e]
            if missing:
                msg += " — " + "; ".join(missing[:4])
        findings.append(_f(gate, Severity.ERROR, f"[{stage}] {msg}"[:1500], target="src/scene.js",
                           hint=_BOOT_HINTS.get(stage, "fix the quoted error"), stage=stage))
    for p in boot.get("camera_problems", []):
        findings.append(_f(gate, Severity(p["severity"]), f"cameras: {p['text']}", target="src/scene.js",
                           hint="cameras: [{name:'overview', position:[x,y,z], lookAt:[x,y,z], fov:50}, ...] (1-6 entries)"))
    if boot.get("ok") and s.get("update_ok") is False:
        findings.append(_f(gate, Severity.ERROR, f"update(t, dt) threw: {s.get('update_error', '')[:800]}", target="src/scene.js",
                           hint="update must run every frame without throwing; guard optional handles"))
    for e in s.get("console_errors", []):
        if e.startswith("boot["):
            continue
        if e.startswith("update(t=") and s.get("update_ok") is False:
            continue
        findings.append(_f(gate, Severity.ERROR, f"console: {e}"[:1000], target="src/scene.js",
                           hint="the browser console must stay clean: fix the quoted error"))
    for w in s.get("console_warnings", []):
        if "404 not found" in w or w.startswith("load: "):
            findings.append(_f(gate, Severity.WARN, w[:500], target="public/assets",
                               hint="compile the Blender asset to public/assets/<name>.glb (the scene renders without it until then)"))
    for e in s.get("shader_errors", []):
        findings.append(_f(gate, Severity.ERROR, f"shader {e.get('stage')}: {e.get('message')} at: {e.get('source_line', '')}",
                           target=e.get("material") or "shader", hint="run shader_probe for the file:line mapping"))
    if boot.get("raf_calls"):
        findings.append(_f(gate, Severity.WARN, f"scene called requestAnimationFrame {boot['raf_calls']}x; animation must live in update(t, dt)",
                           target="src/scene.js", hint="delete your own render loop; the host drives update()"))
    census = s.get("census") or {}
    findings.extend(_census_findings(census))
    return GateReport.of(gate, findings, duration_ms=duration_ms), census


FACT_KEYS = ("fog", "background", "environment", "light_types")


def merge_facts(census: dict[str, Any], facts: Mapping[str, Any]) -> dict[str, Any]:
    """The GLB census with the bpy facts in the keys the gates already read (``fog``,
    ``background``, ``totals.lights`` …) and the rest under ``bpy``."""
    if not census:
        return {}
    out = {**census, **{k: facts[k] for k in FACT_KEYS if k in facts}}
    out["totals"] = {**(census.get("totals") or {}), "lights": int(facts.get("lights") or 0)}
    out["bpy"] = {k: v for k, v in facts.items() if k not in FACT_KEYS and k != "lights"}
    return out


def offline_report(summary: dict[str, Any], facts: Mapping[str, Any], *, duration_ms: int = 0) -> tuple[GateReport, dict[str, Any]]:
    """The ``scene_probe`` gate of an offline scene over its census-GLB probe."""
    boot = summary.get("boot") or {}
    fail = [e for e in summary.get("console_errors", []) if not e.startswith("boot[")]
    if not boot.get("ok"):
        fail.insert(0, f"[{boot.get('stage', '?')}] {boot.get('error') or 'no probe result (driver output lost)'}")
    if fail:
        finding = _f(PROBE_GATE, Severity.ERROR, f"the census GLB did not load cleanly in the probe host: {fail[0]}"[:1500],
                     target="artifacts/census.glb", hint="this is a harness failure, not your code; retry or report",
                     harness_failure=True)
        return GateReport.of(PROBE_GATE, [finding], duration_ms=duration_ms), {}
    findings = [_f(PROBE_GATE, Severity(p["severity"]), f"cameras: {p['text']}", target="src/scene.py",
                   hint="the plan's cameras become src/scene.py CAMERAS at assembly")
                for p in boot.get("camera_problems", [])]
    census = merge_facts(summary.get("census") or {}, facts)
    findings.extend(_census_findings(census, offline=True))
    return GateReport.of(PROBE_GATE, findings, duration_ms=duration_ms), census


def _offline_findings(c: dict[str, Any]) -> list[GateFinding]:
    """What only an offline scene can get wrong."""
    bpy = c.get("bpy") or {}
    out: list[GateFinding] = []
    unique = int(bpy.get("unique_tris") or 0)
    if unique > MAX_TRIS_SCENE:
        out.append(_f(PROBE_GATE, Severity.ERROR,
                      f"{unique:,} unique triangles (instanced copies not counted) exceed the {MAX_TRIS_SCENE:,} budget",
                      target="scene", kind="unique_tris", unique_tris=unique, limit=MAX_TRIS_SCENE,
                      hint="place repeats as collection instances or geometry-nodes instances instead of copies, and lower "
                           "subdivision levels / segment counts on large meshes"))
    for d in (bpy.get("drivers_invalid") or [])[:8]:
        why = "runs Python, which the harness never executes (it evaluates to 0)" if d.get("python") else "is invalid"
        out.append(_f(PROBE_GATE, Severity.ERROR,
                      f"driver {d.get('id')} {d.get('path')}[{d.get('index')}] = {str(d.get('expression'))[:120]!r} {why}",
                      target=str(d.get("id") or "scene"), kind="python_driver",
                      hint="use keyframes, or a simple expression of `frame` (sin/cos/min/max/clamp/lerp, + - * / and "
                           "comparisons, no attribute access, no ** or %)"))
    for h in bpy.get("handlers") or []:
        out.append(_f(PROBE_GATE, Severity.ERROR, f"bpy.app.handlers.{h} is set: the deliverable .blend would depend on "
                      "code that does not travel with it", target="scene", kind="app_handler",
                      hint="animate with keyframes, simple drivers or the geometry-nodes Scene Time node"))
    return out


def _census_findings(c: dict[str, Any], *, offline: bool = False) -> list[GateFinding]:
    gate = PROBE_GATE
    out: list[GateFinding] = []
    if not c:
        return out
    hook_audit = c.get("animation_hooks") or {}
    for hook in hook_audit.get("unobserved", [])[:12]:
        out.append(_f(
            gate, Severity.WARN,
            f"animation hook {hook.get('path', '?')} was not observed during "
            f"update sampling ({hook_audit.get('from_time', 0):g}–{hook_audit.get('to_time', 0):g} s)",
            target=hook.get("zone") or "src/scene.js",
            hint="verify the parent zone forwards update(t, dt) to this asset; captured callback references "
                 "or delayed animation can evade this observation, so inspect before changing code",
            kind="unobserved_animation_hook", hook_path=hook.get("path"),
        ))
    tot = c.get("totals", {})
    if (dark := unlit(c, offline=offline)) is not None:
        out.append(dark)
    if offline:
        if tot.get("meshes", 0) == 0:
            out.append(_f(gate, Severity.ERROR, "scene has no meshes", target="src/scene.py",
                          hint="every zone's build(ctx) links its objects into ctx.collection"))
        out.extend(_offline_findings(c))
    else:
        if tot.get("lights", 0) == 0 and dark is None:
            out.append(_f(gate, Severity.WARN, "scene has no lights (MeshStandardMaterial renders black)", target="src/env.js",
                          hint="add new THREE.DirectionalLight (castShadow) + new THREE.HemisphereLight in buildEnv"))
        if tot.get("meshes", 0) == 0:
            out.append(_f(gate, Severity.ERROR, "scene has no meshes", target="src/scene.js", hint="add zones to the scene in createScene"))
        if tot.get("triangles", 0) > MAX_TRIS_SCENE:
            out.append(_f(gate, Severity.WARN, f"{tot['triangles']:,} triangles exceeds the {MAX_TRIS_SCENE:,} budget", target="scene",
                          hint="lower segment counts, use InstancedMesh for repeats, merge static geometry"))
        out.extend(_draw_findings(c))
    unnamed = [g["name"] for g in c.get("groups", []) if not g.get("named") and g.get("kind") == "content"]
    if unnamed:
        out.append(_f(gate, Severity.WARN, f"{len(unnamed)} top-level content object(s) without a name: {unnamed[:5]}", target="src/scene.js",
                      hint="group each zone in a THREE.Group with group.name = 'ZoneName' (PascalCase)"))
    for o in c.get("overlaps", [])[:5]:
        if o.get("footprint_overlap", 0) >= 0.5:
            out.append(_f(gate, Severity.INFO, f"zones {o['a']} and {o['b']} footprints overlap {o['footprint_overlap']:.0%}",
                          target=o["a"], hint="fine if intended (nested zones); otherwise move one"))
    return out


def unlit(census: Mapping[str, Any], *, offline: bool) -> GateFinding | None:
    """The ERROR for a scene that nothing lights."""
    lights = int((census.get("totals") or {}).get("lights", 0) or 0)
    if lights or census.get("background"):
        return None
    if offline:
        return _f(PROBE_GATE, Severity.ERROR, "scene has no lamps and no world: it renders black", target="src/env.py",
                  kind="unlit", hint="build_env must light the scene: a world (sky or background colour) and/or lamps")
    if census.get("environment"):
        return None
    return _f(PROBE_GATE, Severity.ERROR, "scene has no lights, no scene.background and no scene.environment: it renders black",
              target="src/env.js", kind="unlit",
              hint="buildEnv must light the scene: lights, and the sky as scene.background / scene.environment")


def _draw_findings(c: dict[str, Any]) -> list[GateFinding]:
    """The scene draw budget."""
    draws = int(c.get("totals", {}).get("draws", 0))
    if draws <= DRAWS_WARN_SCENE:
        return []
    sev, limit = (Severity.ERROR, MAX_DRAWS_SCENE) if draws > MAX_DRAWS_SCENE else (Severity.WARN, DRAWS_WARN_SCENE)
    heavy = sorted((g for g in c.get("groups", []) if g.get("draws")), key=lambda g: -g["draws"])[:3]
    where = ", ".join(f"{g['name']} {g['draws']:,}" for g in heavy)
    return [_f(PROBE_GATE, sev,
               f"{draws:,} draw calls per frame (each visible mesh is one) exceed the {limit:,} budget"
               + (f" — most in {where}" if where else "")
               + "; instance repeated geometry with InstancedMesh or merge "
                 "static clutter with BufferGeometryUtils.mergeGeometries",
               target="scene", kind="draw_calls", draws=draws, limit=limit)]


def shader_report(report: dict[str, Any], *, duration_ms: int = 0) -> GateReport:
    """Interpret a shader-preflight report (the ``shader_report`` block of ``probe_scene.mjs
    --compile``) into the ``shader_preflight`` GateReport."""
    gate = SHADER_GATE
    findings: list[GateFinding] = []
    rep = report
    for e in rep.get("errors", []):
        target = f"{e.get('file', '?')}:{e['line']}" if e.get("line") else str(e.get("file", "?"))
        findings.append(_f(gate, Severity.ERROR, e.get("message", "shader error"), target=target,
                           hint=e.get("fix_hint", ""), kind=e.get("kind"), stage=e.get("stage"), material=e.get("material"),
                           source_line=e.get("source_line"), context=e.get("context")))
    for w in rep.get("warnings", []):
        target = f"{w.get('file', '?')}:{w['line']}" if w.get("line") else str(w.get("file", "?"))
        findings.append(_f(gate, Severity.WARN, w.get("message", ""), target=target, hint=w.get("fix_hint", ""), kind=w.get("kind")))
    comp = rep.get("compile") or {}
    if comp:
        findings.append(_f(gate, Severity.INFO, f"compiled {comp.get('programs')} programs ({comp.get('custom_materials')} custom) in {comp.get('ms')} ms",
                           target="scene", **comp))
    passed = bool(rep.get("ok")) and not any(f.severity == Severity.ERROR for f in findings)
    return GateReport(gate=gate, passed=passed, findings=findings, duration_ms=duration_ms)