Skip to content

Official Codebase of 3DCodeVerse

Python

languages: a missing entry file is one typed MissingEntryFile failure in every runtime's build

gaoypenga057e9115285
diff --git a/harness/codeverse3d/languages/_common.py b/harness/codeverse3d/languages/_common.py
index f578d08b..87fa7d7e 100644
--- a/harness/codeverse3d/languages/_common.py
+++ b/harness/codeverse3d/languages/_common.py
@@ -24,6 +24,7 @@ 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
@@ -93,7 +94,23 @@ def read_json_file(path: Path) -> dict[str, Any]:
return data
-def run_wrapper_build(ws: Workspace, *, language: str, entry_rel: str, extras: Mapping[str, str],
+def missing_entry(ws: Workspace, language: Language, *, write: bool = True) -> BuildResult | None:
+ """The one "entry file missing" check every runtime's ``build`` makes after wiping its
+ outputs: a typed ``MISSING_ENTRY`` failure (published as ``build.json`` unless ``write``
+ is off) when ``ENTRY_FILE[language]`` is absent, else ``None``. Until 2026-09-24 five
+ checks gave three outcomes: urdf a ``LintError``, and a scene with no ``scene.js`` a
+ ``scene_probe`` harness failure that no repair was ever asked to fix."""
+ 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
@@ -104,13 +121,10 @@ def run_wrapper_build(ws: Workspace, *, language: str, entry_rel: str, extras: M
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 not (ws.root / entry_rel).is_file():
- result = BuildResult(ok=False, language=language, error_type=MISSING_ENTRY,
- error_message=f"{entry_rel} does not exist", error_file=entry_rel)
- ws.write_json(build_json, result)
- return result
+ 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, proc=proc, build_json=build_json, census_json=ws.artifacts / "census.json",
+ 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)
diff --git a/harness/codeverse3d/languages/blender/__init__.py b/harness/codeverse3d/languages/blender/__init__.py
index 2f2b414b..fc3bbe0d 100644
--- a/harness/codeverse3d/languages/blender/__init__.py
+++ b/harness/codeverse3d/languages/blender/__init__.py
@@ -750,7 +750,7 @@ class BlenderRuntime(RuntimeLayout):
) -> BuildResult:
"""Run the wrapper; never raises for agent-code failures (typed BuildResult instead)."""
return run_wrapper_build(
- ws, language=self.language.value, entry_rel=ENTRY_REL, extras={"stl": "object.stl", "blend": "object.blend"},
+ ws, language=self.language, extras={"stl": "object.stl", "blend": "object.blend"},
argv=lambda: self.build_command(ws, stl=stl, blend=blend, seed=seed, tri_limit=tri_limit),
env=blender_env(), timeout_s=timeout_s or self._settings.limits.build_timeout_s, output_filter=strip_blender_noise)
diff --git a/harness/codeverse3d/languages/cadquery/__init__.py b/harness/codeverse3d/languages/cadquery/__init__.py
index 50818014..bd001eb3 100644
--- a/harness/codeverse3d/languages/cadquery/__init__.py
+++ b/harness/codeverse3d/languages/cadquery/__init__.py
@@ -350,7 +350,7 @@ class CadQueryRuntime(RuntimeLayout):
def build(self, ws: Workspace, *, timeout_s: int | None = None, seed: int = 0,
tri_limit: int = MAX_TRIS_OBJECT) -> BuildResult:
return run_wrapper_build(
- ws, language=self.language.value, entry_rel=ENTRY_FILE[Language.CADQUERY], extras={"step": "object.step", "stl": "object.stl"},
+ ws, language=self.language, extras={"step": "object.step", "stl": "object.stl"},
argv=lambda: self.build_command(ws, seed=seed, tri_limit=tri_limit),
env=cadquery_env(), timeout_s=timeout_s or self._settings.limits.build_timeout_s)
diff --git a/harness/codeverse3d/languages/glsl_shader/__init__.py b/harness/codeverse3d/languages/glsl_shader/__init__.py
index 6eef06b5..65f377ac 100644
--- a/harness/codeverse3d/languages/glsl_shader/__init__.py
+++ b/harness/codeverse3d/languages/glsl_shader/__init__.py
@@ -10,7 +10,7 @@ from pathlib import Path
from codeverse3d.contracts.artifacts import BuildResult, GateFinding, GateReport, Severity
from codeverse3d.contracts.common import ENTRY_FILE, Language
from codeverse3d.contracts.plan import GraphicsPlan, Plan
-from codeverse3d.languages._common import MISSING_ENTRY, line_of, ws_rel
+from codeverse3d.languages._common import line_of, missing_entry, ws_rel
from codeverse3d.languages._gl_common import (
GlslMessage,
LineMap,
@@ -24,7 +24,7 @@ from codeverse3d.languages._gl_common import (
resolution_for,
)
from codeverse3d.languages.base import RuntimeLayout
-from codeverse3d.spatial.gl_render import GlHost, GlResult, gif_times
+from codeverse3d.spatial.gl_render import GlHost, gif_times
from codeverse3d.workspace import Workspace
# ===================================================================== wrap
@@ -429,9 +429,8 @@ class GlslShaderRuntime(RuntimeLayout):
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 not (ws.root / SHADER).is_file():
- res = GlResult(ok=False, mode="shader", stage="lint", error_type=MISSING_ENTRY, error_message=f"{SHADER} is missing")
- return finish_build(ws, res, language=self.language.value, error_file=SHADER)
+ if (missing := missing_entry(ws, self.language)) is not None:
+ return missing
plan = graphics_plan(ws)
w, h = resolution_for(plan)
if width and height:
diff --git a/harness/codeverse3d/languages/opengl_python/__init__.py b/harness/codeverse3d/languages/opengl_python/__init__.py
index 6af617e5..b548ba06 100644
--- a/harness/codeverse3d/languages/opengl_python/__init__.py
+++ b/harness/codeverse3d/languages/opengl_python/__init__.py
@@ -15,7 +15,7 @@ from codeverse3d.languages._ast_lint import (
describe_parse_failure,
safe_parse,
)
-from codeverse3d.languages._common import MISSING_ENTRY, ws_rel
+from codeverse3d.languages._common import missing_entry, ws_rel
from codeverse3d.languages._gl_common import (
finish_build,
graphics_plan,
@@ -27,7 +27,7 @@ from codeverse3d.languages._gl_common import (
traceback_location,
)
from codeverse3d.languages.base import RuntimeLayout
-from codeverse3d.spatial.gl_render import GlHost, GlResult, gif_times
+from codeverse3d.spatial.gl_render import GlHost, gif_times
from codeverse3d.workspace import Workspace
# ===================================================================== lint
@@ -357,10 +357,9 @@ class OpenGLPythonRuntime(RuntimeLayout):
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
- if not program.is_file():
- res = GlResult(ok=False, mode="program", stage="lint", error_type=MISSING_ENTRY, error_message=f"{PROGRAM} is missing")
- return finish_build(ws, res, language=self.language.value, error_file=PROGRAM)
plan = graphics_plan(ws)
w, h = resolution_for(plan)
if width and height:
diff --git a/harness/codeverse3d/languages/scene_threejs/__init__.py b/harness/codeverse3d/languages/scene_threejs/__init__.py
index c2fff44b..abfc606d 100644
--- a/harness/codeverse3d/languages/scene_threejs/__init__.py
+++ b/harness/codeverse3d/languages/scene_threejs/__init__.py
@@ -19,7 +19,7 @@ from codeverse3d.contracts.artifacts import (
from codeverse3d.contracts.common import ENTRY_FILE, Language
from codeverse3d.contracts.plan import AssetPlan, CameraPlan, Plan, ScenePlan, ZonePlan
from codeverse3d.conventions import OBJECT_VIEWS_QUICK, to_pascal, to_snake
-from codeverse3d.languages._common import line_of, ws_rel
+from codeverse3d.languages._common import line_of, missing_entry, ws_rel
from codeverse3d.languages._js_lint import (
ImportKind,
ImportVerdict,
@@ -741,6 +741,8 @@ class SceneThreeJsRuntime:
# driver outputs (scene_probe.json / shader_preflight.json) looking current;
# census.json is only rewritten `if census:` below, so it MUST be wiped here
ws.stage_artifacts("census.json", "scene_probe.json", "shader_preflight.json", "build.json").invalidate()
+ if (missing := missing_entry(ws, self.language)) is not None:
+ return missing
from codeverse3d.spatial.probes import run_probe
probe, shaders, census = run_probe(ws, compile=True, timeout_s=timeout_s)
diff --git a/harness/codeverse3d/languages/threejs/__init__.py b/harness/codeverse3d/languages/threejs/__init__.py
index 80e07148..56e224e2 100644
--- a/harness/codeverse3d/languages/threejs/__init__.py
+++ b/harness/codeverse3d/languages/threejs/__init__.py
@@ -12,7 +12,7 @@ from codeverse3d.contracts.artifacts import BuildResult, GateFinding, GateReport
from codeverse3d.contracts.common import ENTRY_FILE, Language
from codeverse3d.contracts.plan import Plan, StaticPlan
from codeverse3d.conventions import to_pascal, to_snake
-from codeverse3d.languages._common import BUILD_TIMEOUT, line_of, ws_rel
+from codeverse3d.languages._common import BUILD_TIMEOUT, line_of, missing_entry, ws_rel
from codeverse3d.languages._js_lint import (
ImportKind,
ImportVerdict,
@@ -346,6 +346,8 @@ class ThreeJsRuntime(RuntimeLayout):
# build.json is in the wipe too: the node-missing raise below returns before
# _write_build_json, and a stale ok:true build.json must not survive it
ws.stage_artifacts(GLB_NAME, CENSUS_NAME, BUILD_JSON, "export_error.json").invalidate()
+ if (missing := missing_entry(ws, self.language)) is not None:
+ return missing
self._ensure_module_type(ws)
t0 = time.time()
diff --git a/harness/codeverse3d/languages/urdf/__init__.py b/harness/codeverse3d/languages/urdf/__init__.py
index f6842d9b..b7f8833c 100644
--- a/harness/codeverse3d/languages/urdf/__init__.py
+++ b/harness/codeverse3d/languages/urdf/__init__.py
@@ -30,7 +30,7 @@ from codeverse3d.languages._ast_lint import (
dotted,
safe_parse,
)
-from codeverse3d.languages._common import compose_build_result, strip_blender_noise
+from codeverse3d.languages._common import compose_build_result, missing_entry, strip_blender_noise
from codeverse3d.languages.base import RuntimeLayout
from codeverse3d.proc import ProcResult, run_subprocess
from codeverse3d.spatial.joints_export import urdf_to_glb
@@ -777,6 +777,8 @@ class UrdfBlenderRuntime(RuntimeLayout):
error_message=message, error_file=file, error_line=line,
duration_ms=int((time.time() - t0) * 1000), census=census or {}, **kw))
+ if (missing := missing_entry(ws, self.language, write=False)) is not None:
+ return finish(missing)
# 1. lint (cheap, no Blender)
lint = self.lint(ws)
census: dict[str, Any] = {"lint": [f.model_dump(mode="json") for f in lint.findings]}
diff --git a/harness/tests/languages/test_missing_entry.py b/harness/tests/languages/test_missing_entry.py
new file mode 100644
index 00000000..73f3ea66
--- /dev/null
+++ b/harness/tests/languages/test_missing_entry.py
@@ -0,0 +1,20 @@
+"""Every runtime's build answers a missing entry file the same way (audit 2026-09-24 N21)."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from codeverse3d.contracts.common import ENTRY_FILE, Language
+from codeverse3d.languages.base import get_runtime
+
+
[email protected]("language", list(Language))
+def test_a_missing_entry_is_one_typed_repairable_failure(tmp_ws, language: Language) -> None:
+ """Regression: a scene with no scene.js was a `scene_probe` harness failure (never repaired)
+ and urdf a `LintError`; now all seven return MissingEntryFile, as build.json says too."""
+ res = get_runtime(language).build(tmp_ws)
+ assert (res.ok, res.error_type, res.error_file, res.harness_failure) == \
+ (False, "MissingEntryFile", ENTRY_FILE[language], False)
+ assert json.loads((tmp_ws.artifacts / "build.json").read_text())["error_type"] == "MissingEntryFile"
diff --git a/harness/tests/scene_runtime/test_runtime.py b/harness/tests/scene_runtime/test_runtime.py
index eeef5966..bc0d788b 100644
--- a/harness/tests/scene_runtime/test_runtime.py
+++ b/harness/tests/scene_runtime/test_runtime.py
@@ -106,6 +106,7 @@ def test_build_interprets_combined_summary_offline(ws, monkeypatch):
import codeverse3d.spatial.probes as probes_mod
monkeypatch.setattr(probes_mod, "run_scene_script", fake_run)
+ (ws.src / "scene.js").write_text("export function createScene() {}\n")
res = rt_mod.SceneThreeJsRuntime().build(ws)
assert len(calls) == 1 and calls[0][0] == "probe_scene.mjs" and "--compile" in calls[0]
assert not res.ok # shader gate failed
diff --git a/harness/tests/threejs_render/test_build.py b/harness/tests/threejs_render/test_build.py
index e466d340..02fbbd27 100644
--- a/harness/tests/threejs_render/test_build.py
+++ b/harness/tests/threejs_render/test_build.py
@@ -44,11 +44,10 @@ def test_build_stool_glb_and_census(stool_build, stool_ws: Workspace):
lo, hi = scene.bounds
assert np.allclose(lo, [-0.17, 0.0, -0.17], atol=2e-3)
assert np.allclose(hi, [0.17, 0.45, 0.17], atol=2e-3)
- # no entry module: the exporter's typed error, with its record on disk
+ # no entry module: the shared typed failure, before any node boot, and the GLB is wiped
(stool_ws.src / "object.js").unlink()
res = ThreeJsRuntime().build(stool_ws)
- assert not res.ok and res.error_type == "MissingEntryFile"
- assert (stool_ws.artifacts / "export_error.json").is_file()
+ assert not res.ok and res.error_type == "MissingEntryFile" and not (stool_ws.artifacts / "object.glb").exists()
@pytest.mark.parametrize("path, find, repl, etype, line", [