Skip to content

Official Codebase of 3DCodeVerse

Python
8.0 KB
Raw Blame
"""Shared helpers for the language runtimes: the python wrapper build (blender, cadquery, urdf),
finding locations and the typed failure names every lint uses.

Wrappers are standalone scripts in ``languages/wrappers/``; they never import ``codeverse3d``.
"""

from __future__ import annotations

import json
from collections.abc import Callable, Mapping
from pathlib import Path
from typing import Any

from codeverse3d.contracts.artifacts import BuildResult
from codeverse3d.contracts.common import ENTRY_FILE, Language
from codeverse3d.proc import ProcResult, read_json_or_none, run_subprocess, tail, write_json_atomic
from codeverse3d.workspace import Workspace

#: The one spelling of every runtime's typed build failures (recorded in build.json / record.json).
MISSING_ENTRY = "MissingEntryFile"
BUILD_TIMEOUT = "BuildTimeout"

# lines Blender prints on every headless run that carry no signal for the agent
_BLENDER_NOISE_PREFIXES = (
    "Blender ",
    "Read prefs",
    "Color management",
    "Warning: Falling back",
    "ALSA lib",
    "libEGL",
    "MESA",
    "glx:",
    "Xlib:",
    "Unable to open a display",
    "Blender quit",
    "Saved session recovery",
    "Info: ",
    "INFO Draco",
    "Timer '",
)
_BLENDER_NOISE_SUBSTR = ("| INFO: ", "| WARNING: Draco")


class WrapperError(RuntimeError):
    """The wrapper process did not produce a readable ``build.json`` (harness bug or crash)."""


def line_of(text: str, pos: int) -> int:
    """1-based line of character offset ``pos``."""
    return text.count("\n", 0, pos) + 1


def target_file(target: str | None) -> str:
    """``src/zones/a.js:12`` → ``src/zones/a.js`` (a finding's target without its line)."""
    if not target:
        return ""
    head, sep, tail = target.rpartition(":")
    return head if sep and tail.isdigit() else target


def target_line(target: str | None) -> int | None:
    """``src/zones/a.js:12`` → ``12``; ``None`` when the target names no line."""
    if not target:
        return None
    _, sep, tail = target.rpartition(":")
    return int(tail) if sep and tail.isdigit() else None


def ws_rel(ws: Workspace, p: Path) -> str:
    """``p`` workspace-relative (posix), or as given when it lies outside the workspace."""
    try:
        return p.relative_to(ws.root).as_posix()
    except ValueError:
        return str(p)


def strip_blender_noise(text: str) -> str:
    """Drop Blender's boilerplate stderr/stdout lines so the agent sees signal only."""
    keep = [
        ln for ln in text.splitlines()
        if ln.strip() and not ln.startswith(_BLENDER_NOISE_PREFIXES) and not any(s in ln for s in _BLENDER_NOISE_SUBSTR)
    ]
    return "\n".join(keep)


def read_json_file(path: Path) -> dict[str, Any]:
    """Parse a JSON object file; raise :class:`WrapperError` if missing/invalid."""
    if not path.is_file():
        raise WrapperError(f"expected wrapper output missing: {path}")
    try:
        data = json.loads(path.read_text())
    except ValueError as e:
        raise WrapperError(f"invalid JSON in {path}: {e}") from e
    if not isinstance(data, dict):
        raise WrapperError(f"{path}: expected a JSON object")
    return data


def missing_entry(ws: Workspace, language: Language, *, write: bool = True) -> BuildResult | None:
    """Typed ``MISSING_ENTRY`` failure (published as ``build.json`` unless ``write`` is off) when the entry file is absent, else ``None``."""
    entry = ENTRY_FILE[language]
    if (ws.root / entry).is_file():
        return None
    result = BuildResult(ok=False, language=language.value, error_type=MISSING_ENTRY,
                         error_message=f"{entry} does not exist", error_file=entry)
    if write:
        ws.write_json(ws.artifacts / "build.json", result)
    return result


def run_wrapper_build(ws: Workspace, *, language: Language, extras: Mapping[str, str],
                      argv: Callable[[], list[str]], env: dict[str, str], timeout_s: float,
                      output_filter: Callable[[str], str] | None = None) -> BuildResult:
    """Run a python wrapper build; ``extras`` maps a ``BuildResult.extra_paths`` key to its artifact file name.

    Outputs are invalidated before the missing-entry return so a stale glb never looks current."""
    ws.artifacts.mkdir(parents=True, exist_ok=True)
    build_json = ws.artifacts / "build.json"
    ws.stage_artifacts("build.json", "census.json", "object.glb", *extras.values()).invalidate()
    if (missing := missing_entry(ws, language)) is not None:
        return missing
    proc = run_subprocess(argv(), cwd=ws.root, env=env, timeout_s=timeout_s)
    return compose_build_result(language=language.value, proc=proc, build_json=build_json, census_json=ws.artifacts / "census.json",
                                glb_path=ws.artifacts / "object.glb", extra_paths={k: ws.artifacts / v for k, v in extras.items()},
                                output_filter=output_filter)


def compose_build_result(
    *,
    language: str,
    proc: ProcResult,
    build_json: Path,
    census_json: Path,
    glb_path: Path | None,
    extra_paths: Mapping[str, Path],
    output_filter: Callable[[str], str] | None = None,
    publish: bool = True,
) -> BuildResult:
    """Merge the wrapper's ``build.json`` with the process outcome and write the result over it.

    Success requires wrapper ``ok`` and, when ``glb_path`` is set, a non-empty GLB.  Timeouts and
    crashes become a failed BuildResult.  ``publish=False`` leaves ``build_json`` as the wrapper wrote it."""
    stdout_tail = tail(output_filter(proc.stdout) if output_filter else proc.stdout)
    stderr_tail = tail(output_filter(proc.stderr) if output_filter else proc.stderr)
    base = dict(language=language, stdout_tail=stdout_tail, stderr_tail=stderr_tail, duration_ms=proc.duration_ms)
    if proc.timed_out:
        res = BuildResult(
            ok=False,
            error_type=BUILD_TIMEOUT,
            error_message=f"build exceeded the time limit ({proc.duration_ms // 1000}s); "
            "reduce geometry (subdivisions, array counts, boolean ops) so the script finishes quickly",
            **base,
        )
    elif not build_json.is_file():
        res = BuildResult(
            ok=False,
            error_type="WrapperCrash",
            error_message=(
                f"the build wrapper exited with code {proc.returncode} before reporting; "
                "see stderr_tail (memory cap hit / interpreter crash / missing dependency)"
            ),
            **base,
        )
    else:
        res = _merge_report(read_json_file(build_json), census_json, glb_path, extra_paths, base)
    if publish:
        write_json_atomic(build_json, res.model_dump(mode="json"))
    return res


def _merge_report(data: dict[str, Any], census_json: Path, glb_path: Path | None,
                  extra_paths: Mapping[str, Path], base: dict[str, Any]) -> BuildResult:
    census = read_json_or_none(census_json) or {}
    # keep the wrapper's extra diagnostics (traceback, warnings …) next to the census
    census["build_report"] = {k: data[k] for k in ("traceback", "error_source", "warnings", "exported", "exec_ms") if k in data}
    glb_ok = glb_path is None or (glb_path.is_file() and glb_path.stat().st_size > 0)
    ok = bool(data.get("ok")) and glb_ok
    error_type = str(data.get("error_type") or "")
    error_message = str(data.get("error_message") or "")
    if data.get("ok") and not glb_ok:
        error_type = error_type or "ExportEmpty"
        error_message = error_message or "the script ran but no mesh geometry was exported (object.glb empty)"
    extras = {k: str(p) for k, p in extra_paths.items() if p.is_file() and p.stat().st_size > 0}
    line = data.get("error_line")
    return BuildResult(
        ok=ok,
        glb_path=str(glb_path) if glb_path is not None and glb_ok else None,
        extra_paths=extras,
        error_type=error_type,
        error_message=error_message,
        error_file=str(data.get("error_file") or ""),
        error_line=int(line) if isinstance(line, int) else None,
        census=census,
        **{**base, "duration_ms": int(data.get("duration_ms") or base["duration_ms"])},
    )