Skip to content

Official Codebase of 3DCodeVerse

Python
12.3 KB
Raw Blame
"""opengl_python language: raw OpenGL (moderngl) programs rendered headless by the harness."""

from __future__ import annotations

import ast
import re

from codeverse3d.contracts.artifacts import BuildResult, GateFinding, GateReport, Severity
from codeverse3d.contracts.common import ENTRY_FILE, Language
from codeverse3d.languages._ast_lint import (
    BASE_FORBIDDEN_IMPORTS,
    check_imports,
    describe_parse_failure,
    safe_parse,
)
from codeverse3d.languages._common import missing_entry, ws_rel
from codeverse3d.languages._gl_common import (
    finish_build,
    graphics_plan,
    invalidate_stale_outputs,
    judge_times,
    make_host,
    parse_glsl_log,
    resolution_for,
    traceback_location,
)
from codeverse3d.languages.base import RuntimeLayout
from codeverse3d.spatial.gl_render import GlHost, gif_times
from codeverse3d.workspace import Workspace

# ===================================================================== lint
GATE = "lint:opengl_python"
PROGRAM = ENTRY_FILE[Language.OPENGL_PYTHON]
ALLOWED_MODULES: frozenset[str] = frozenset({
    "moderngl", "numpy", "math", "random", "struct", "array", "pathlib", "typing", "dataclasses", "itertools",
    "functools", "collections", "colorsys", "__future__", "enum",
})
WINDOW_LIBS = {"glfw", "pygame", "pyglet", "PyQt5", "PyQt6", "PySide2", "PySide6", "tkinter", "moderngl_window", "sdl2", "wx", "OpenGL"}
DANGEROUS_MODULES = frozenset(BASE_FORBIDDEN_IMPORTS | {
    "os", "sys",  # no interpreter / file-system access
    "signal", "tempfile", "io", "time", "datetime",  # frames must be a pure, deterministic function of t
})
FORBIDDEN_CALLS = {"open", "exec", "eval", "compile", "__import__", "input", "exit", "quit", "breakpoint"}
MAX_CHARS = 120_000
_VERSION_RE = re.compile(r"#\s*version\s+(\d+)(?:\s+(\w+))?")


def _finding(sev: Severity, kind: str, msg: str, hint: str, line: int | None = None) -> GateFinding:
    return GateFinding(gate=GATE, severity=sev, target=PROGRAM, message=(f"{PROGRAM}:{line}: " if line else f"{PROGRAM}: ") + msg,
                       fix_hint=hint, data={"kind": kind, "line": line, "file": PROGRAM})


def _root(name: str) -> str:
    return name.split(".", 1)[0]


class _Visitor(ast.NodeVisitor):
    def __init__(self) -> None:
        self.findings: list[GateFinding] = []
        self.funcs: dict[str, ast.FunctionDef] = {}
        self.seeded = False
        self.uses_random = False

    # imports -------------------------------------------------------------
    def _check_module(self, name: str, line: int) -> None:
        root = _root(name)
        if root in WINDOW_LIBS:
            self.findings.append(_finding(Severity.ERROR, "window_lib", f"imports `{name}` (window / input library)",
                                          "the harness creates the context and framebuffer; draw into the fbo it passes — no window", line))
            return

        def _import_finding(kind: str, _mod: str, ln: int) -> GateFinding:
            if kind == "forbidden":
                return _finding(Severity.ERROR, "forbidden_import", f"imports `{name}` (not allowed in a rendering program)",
                                "allowed: " + ", ".join(sorted(ALLOWED_MODULES)), ln)
            return _finding(Severity.ERROR, "forbidden_import", f"imports `{name}` which is outside the allow-list",
                            "use only moderngl + numpy + stdlib math/random/struct/array/pathlib", ln)

        self.findings.extend(check_imports({root: line}, forbidden=DANGEROUS_MODULES, allowed=ALLOWED_MODULES,
                                           make_finding=_import_finding))

    def visit_Import(self, node: ast.Import) -> None:
        for a in node.names:
            self._check_module(a.name, node.lineno)
        self.generic_visit(node)

    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
        if node.module:
            self._check_module(node.module, node.lineno)
        self.generic_visit(node)

    # calls ---------------------------------------------------------------
    def visit_Call(self, node: ast.Call) -> None:
        fn = node.func
        name = fn.id if isinstance(fn, ast.Name) else None
        attr = fn.attr if isinstance(fn, ast.Attribute) else None
        base = fn.value.id if isinstance(fn, ast.Attribute) and isinstance(fn.value, ast.Name) else None
        if name in FORBIDDEN_CALLS:
            self.findings.append(_finding(Severity.ERROR, "forbidden_call", f"calls `{name}()`",
                                          "no file/console IO: put GLSL in triple-quoted strings, or Path(__file__).with_name('x.glsl').read_text()",
                                          node.lineno))
        if attr in ("create_context", "create_standalone_context") and base == "moderngl":
            self.findings.append(_finding(Severity.ERROR, "own_context", "creates its own moderngl context",
                                          "use the `ctx` passed to setup()/render(); never create a context or window", node.lineno))
        if base == "time" and attr in ("time", "perf_counter", "monotonic"):
            self.findings.append(_finding(Severity.ERROR, "wall_clock", "reads the wall clock", "use the `t` argument of render(); frames must be a pure function of t", node.lineno))
        if base == "random" and attr == "seed":
            self.seeded = True
        if base == "random" and attr in ("random", "uniform", "randint", "gauss", "choice", "shuffle"):
            self.uses_random = True
        if base in ("np", "numpy") and attr == "seed":
            self.seeded = True
        if attr == "default_rng":   # np.random.default_rng(seed) — the seeding the contract recommends
            self.seeded = True
        if attr in ("write_text", "write_bytes", "unlink", "mkdir", "rmdir", "rename"):
            self.findings.append(_finding(Severity.ERROR, "file_write", f"calls `.{attr}()` (file system write)", "programs never write files", node.lineno))
        if attr == "read_text" or attr == "read_bytes":
            self.findings.append(_finding(Severity.INFO, "read_file", f"reads a file via `.{attr}()` — only src/*.glsl shipped next to program.py is allowed",
                                          "Path(__file__).with_name('x.glsl').read_text()", node.lineno))
        self.generic_visit(node)

    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
        self.funcs[node.name] = node
        self.generic_visit(node)

    def visit_Constant(self, node: ast.Constant) -> None:
        if isinstance(node.value, str) and "#version" in node.value:
            m = _VERSION_RE.search(node.value)
            if m and (m.group(1) != "330" or (m.group(2) or "core") != "core"):
                self.findings.append(_finding(Severity.WARN, "glsl_version", f"GLSL string uses `#version {m.group(1)} {m.group(2) or ''}`; the context is GL 3.3 core",
                                              "use `#version 330 core` in every shader string", node.lineno))
        if isinstance(node.value, str) and "gl_FragColor" in node.value:
            self.findings.append(_finding(Severity.ERROR, "legacy_glsl", "GLSL string uses gl_FragColor (GLSL 1.x)",
                                          "declare `out vec4 fragColor;` and write it (GLSL 330 core)", node.lineno))
        if isinstance(node.value, str) and ("attribute " in node.value or "varying " in node.value) and "#version" in node.value:
            self.findings.append(_finding(Severity.ERROR, "legacy_glsl", "GLSL string uses attribute/varying (GLSL 1.x)",
                                          "use `in` / `out` qualifiers (GLSL 330 core)", node.lineno))


def lint_source(text: str) -> list[GateFinding]:
    findings: list[GateFinding] = []
    if len(text) > MAX_CHARS:
        findings.append(_finding(Severity.WARN, "too_long", f"file is {len(text)} chars", "keep the program focused"))
    tree, exc = safe_parse(text)
    if tree is None:
        msg, hint, line = describe_parse_failure(exc)  # type: ignore[arg-type]
        findings.append(_finding(Severity.ERROR, "syntax", msg, hint if not isinstance(exc, SyntaxError) else "fix the syntax at this line", line))
        return findings
    v = _Visitor()
    v.visit(tree)
    findings.extend(v.findings)
    for fn, nargs in (("setup", 3), ("render", 5)):
        node = v.funcs.get(fn)
        if node is None:
            findings.append(_finding(Severity.ERROR, "missing_entry", f"missing `def {fn}(...)`",
                                     "def setup(ctx, width, height) -> state  and  def render(ctx, state, t, frame, fbo) -> None"))
        elif len(node.args.args) != nargs and node.args.vararg is None:
            findings.append(_finding(Severity.ERROR, "bad_signature", f"`{fn}` takes {len(node.args.args)} positional args, expected {nargs}",
                                     "setup(ctx, width, height) / render(ctx, state, t, frame, fbo)", node.lineno))
    if v.uses_random and not v.seeded:
        findings.append(_finding(Severity.WARN, "unseeded_random", "uses random.* without random.seed(...) or a default_rng(...)",
                                 "call random.seed(0) / np.random.default_rng(0) in setup() so frames are reproducible"))
    return findings


def lint_workspace(ws: Workspace) -> GateReport:
    p = ws.root / PROGRAM
    if not p.is_file():
        f = [_finding(Severity.ERROR, "missing_entry", f"{PROGRAM} is missing",
                      "create src/program.py with setup(ctx, width, height) and render(ctx, state, t, frame, fbo)")]
        return GateReport.of(GATE, f)
    findings = lint_source(p.read_text(errors="replace"))
    for extra in sorted(ws.src.rglob("*.py")):
        rel = ws_rel(ws, extra)
        if rel != PROGRAM:
            findings.append(GateFinding(gate=GATE, severity=Severity.WARN, target=rel, message=f"{rel}: extra python module is not part of the deliverable (only src/program.py and src/*.glsl are)",
                                        fix_hint="keep all code in src/program.py (GLSL may live in src/*.glsl)", data={"kind": "stray_file", "file": rel}))
    return GateReport.of(GATE, findings)


# ===================================================================== skeleton


# ===================================================================== runtime
class OpenGLPythonRuntime(RuntimeLayout):
    language = Language.OPENGL_PYTHON
    entry_globs: tuple[str, ...] = (ENTRY_FILE[Language.OPENGL_PYTHON], "src/*.glsl")

    def __init__(self, *, host: GlHost | None = None):
        self._host = host


    def lint(self, ws: Workspace) -> GateReport:
        return lint_workspace(ws)

    # ------------------------------------------------------------------ build
    def host(self, timeout_s: float | None = None) -> GlHost:
        return make_host(self._host, timeout_s)

    def build(self, ws: Workspace, *, timeout_s: int | None = None, times: list[float] | None = None,
              preview: bool = True, width: int | None = None, height: int | None = None) -> BuildResult:
        ws.artifacts.mkdir(parents=True, exist_ok=True)
        invalidate_stale_outputs(ws)  # BEFORE the MISSING_ENTRY return, so it also clears
        if (missing := missing_entry(ws, self.language)) is not None:
            return missing
        program = ws.root / PROGRAM
        plan = graphics_plan(ws)
        w, h = resolution_for(plan)
        if width and height:
            w, h = int(width), int(height)
        duration = plan.duration_s if plan else None
        res = self.host(timeout_s).run_program(program, ws.artifacts, width=w, height=h, times=times or judge_times(duration),
                                               extra_times=gif_times(duration or 8.0) if preview else (), cwd=ws.src)
        err_file, err_line, err_msg = "", None, None
        if not res.ok:
            err_file, err_line = traceback_location(res.traceback, program)
            err_msg = f"{res.stage} failed: {res.error_type}: {res.error_message}"
            glsl = parse_glsl_log(res.error_message)
            if glsl:
                res.error_type = "GlslCompileError"
                err_msg += "\n(GLSL line numbers refer to the shader STRING inside program.py: " + \
                           "; ".join(f"line {m.line}: {m.message}" for m in glsl[:8]) + ")"
        motion_expected = bool(plan.motion.strip()) if plan else True
        return finish_build(ws, res, language=self.language.value, error_file=err_file, error_line=err_line,
                            error_message=err_msg, motion_expected=motion_expected)