Files
Patryk GenschandClaude Opus 5.5 7d85a69274 feat(tracker): report a scene module under the engine it runs in
Binaries from a module snapshot carry host_family (from module_of); the
roadmap lists a module type's presence by that engine family.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 21:00:23 +01:00

402 lines
22 KiB
Python

from copy import deepcopy
import json
from pathlib import Path
import pytest
from ams.snapshot import Snapshot
from ams.tracker import build_tracker, load_reviews, scan_emulator
SHA = "a" * 64
def emulator(tmp_path):
directory = tmp_path / "core/src/pl/genschu/bloomooemulator/interpreter/variable"
directory.mkdir(parents=True)
(directory / "Variable.java").write_text('''interface Variable {
Map.entry("CLONE", MethodSpec.of((s,a,c) -> clone(s)));
}''')
(directory / "BoolVariable.java").write_text('''record BoolVariable() {
VariableType type() { return VariableType.BOOLEAN; }
// Map.entry("FAKE", MethodSpec.of((s,a,c) -> null));
String misleading = "Map.entry(\\"FAKE2\\", MethodSpec.of(";
Map.entry("SET", MethodSpec.of((s,a,c) -> {
String x = ") /*"; // )
return new Value(a.get(0));
}));
Map.entry("TODO", MethodSpec.of((s,a,c) -> {
throw new UnsupportedOperationException("todo");
}));
Map.entry("NOOP", MethodSpec.of((s,a,c) -> MethodResult.noReturn()));
}''')
result = scan_emulator(tmp_path)
result["commit"] = "f" * 40
return result
def native(sha=SHA):
return Snapshot({"binary": {"name": "test.dll", "sha256": sha},
"types": [{"script_name": "BOOL", "cpp_class": "CMC_Bool"},
{"script_name": "UNKNOWN", "cpp_class": None}],
"methods": [{"owner": "CMC_Bool", "name": "set", "id": 1},
{"owner": "CMC", "name": "CLONE", "id": 1},
{"owner": "CMC", "name": "SET", "id": 2}],
"method_inheritance": [{"runner": "CMC_Bool_Runner", "base_runner": "CMC_Runner"}],
"method_dispatch": [{"owner": "CMC_Bool", "id": 1, "impl_addr": "0x10001000"}]})
def row(result, typ="BOOLEAN", method="SET"):
return next(m for t in result["types"] if t["name"] == typ for m in t["methods"] if m["name"] == method)
def review(emu, **changes):
return {"type": "BOOLEAN", "method": "SET", "binary_sha256": SHA, "rva": "0x1000",
"emulator_commit": emu["commit"], "body_sha256": emu["types"]["BOOLEAN"]["methods"]["SET"]["source"]["body_sha256"],
"source_tree_sha256": emu["source_tree_sha256"], "reviewer": "test", "date": "2026-10-10",
"notes": "Checked integer input", "evidence": "evidence/example.json#method", "kind": "asm",
"verdict": "matches", **changes}
def test_java_adapter_ignores_comments_literals_and_balances(tmp_path):
emu = emulator(tmp_path)
methods = emu["types"]["BOOLEAN"]["methods"]
assert set(methods) == {"SET", "TODO", "NOOP"}
assert methods["TODO"]["status"] == "stub_candidate"
assert methods["NOOP"]["status"] == "registered"
assert methods["SET"]["source"]["line"] == 5
def test_inheritance_aliases_and_globals_are_not_implementation_proof(tmp_path):
result = build_tracker([native()], emulator(tmp_path))
assert row(result)["status"] == "registered"
assert row(result)["verification"] == "unverified"
assert row(result)["original"][0]["owner"] == "CMC_Bool"
assert len(row(result)["original"]) == 1 # child wins over SET on base
assert row(result, "*", "CLONE")["source"]["owner"] == "*"
assert not row(result, "*", "CLONE")["original"][0]["inherited"]
assert typ(result, "BOOLEAN")["inherits"] == ["*"]
assert "CLONE" not in {m["name"] for m in typ(result, "BOOLEAN")["methods"]} # listed once, under *
assert typ(result, "UNKNOWN")["methods"] == []
def factory_snapshot():
"""Piklib 8 shape: five variable types share one runner, VECTOR's runner has no symbol."""
return Snapshot({"binary": {"name": "p8.dll", "sha256": SHA},
"types": [{"script_name": "INTEGER", "cpp_class": "CMC_Integer", "type_id": 1},
{"script_name": "STRING", "cpp_class": "CMC_String", "type_id": 2},
{"script_name": "VECTOR", "cpp_class": None, "type_id": 0x7e0}],
"methods": [{"owner": "CMC_Variable", "runner": "CMC_Variable_Runner", "name": "ADD", "id": 6},
{"owner": "CMC_Variable", "runner": "CMC_Variable_Runner", "name": "UPPER", "id": 30},
{"owner": "CMC_Vector", "runner": "CMC_Vector_Runner", "name": "NORMALIZE", "id": 8},
{"owner": "CMC_Dummy", "runner": "CMC_Dummy_Runner", "name": "IF", "id": 1},
{"owner": "CMC_Dummy", "runner": "CMC_Dummy_Runner", "name": "MSGBOX", "id": 6},
{"owner": "CMC", "runner": "CMC_Runner", "name": "CLONE", "id": 100}],
"method_inheritance": [{"runner": "CMC_Variable_Runner", "base_runner": "CMC_Runner"},
{"runner": "CMC_Vector_Runner", "base_runner": "CMC_Runner"}],
"method_dispatch": [
{"owner": "CMC_Variable", "runner": "CMC_Variable_Runner", "id": 6, "params": [{"index": 0, "types": ["int"]}],
"variadic": False, "returns": ["copy"], "per_type": {"INTEGER": "trivial_virtual", "STRING": "applies"}},
{"owner": "CMC_Variable", "runner": "CMC_Variable_Runner", "id": 30, "params": [], "variadic": False,
"returns": [], "per_type": {"INTEGER": "excluded_by_type_check", "STRING": "applies"}}],
"runner_map": {"by_type_id": [{"type_id": 0, "runner": "CMC_Dummy_Runner"},
{"type_id": 1, "runner": "CMC_Variable_Runner"},
{"type_id": 2, "runner": "CMC_Variable_Runner"},
{"type_id": 0x7e0, "runner": "CMC_Vector_Runner"}]}})
def typ(result, name):
return next(t for t in result["types"] if t["name"] == name)
def test_runner_factory_maps_shared_and_unnamed_runners(tmp_path):
result = build_tracker([factory_snapshot()], emulator(tmp_path))
names = {t["name"] for t in result["types"]}
assert {"INTEGER", "STRING", "VECTOR", "@", "*"} <= names
assert not {"VARIABLE", "VECTOR_RUNNER", "DUMMY"} & names # no pseudo-types from runner classes
for name in ("INTEGER", "STRING"):
add = row(result, name, "ADD")["original"][0]
assert (add["owner"], add["mapping"], add["inherited"]) == ("CMC_Variable", "runner_factory", False)
assert any("Wspólny runner CMC_Variable_Runner" in n for n in typ(result, name)["mapping_notes"])
assert row(result, "VECTOR", "NORMALIZE")["original"]
assert {m["name"] for m in typ(result, "@")["methods"]} == {"IF", "MSGBOX"}
assert "inherits" not in typ(result, "@") # built-ins do not chain to CMC_Runner
def test_scene_module_types_map_through_the_runner_their_objects_install(tmp_path):
module = Snapshot({"binary": {"name": "Matrix.dll", "sha256": "b" * 64, "module_of": "PIKLIB8.DLL"},
"types": [{"script_name": "MATRIX", "cpp_class": None, "type_id": 10002}],
"methods": [{"owner": "CMC_Matrix", "runner": "CMC_Matrix_Runner", "name": "TICK", "id": 1}],
"method_inheritance": [{"runner": "CMC_Matrix_Runner", "base_runner": "CMC_Runner"}],
"runner_map": {"module": True, "by_type_id": [{"type_id": 10002, "runner": "CMC_Matrix_Runner"}]}})
result = build_tracker([factory_snapshot(), module], emulator(tmp_path))
tick = row(result, "MATRIX", "TICK")["original"][0]
assert (tick["owner"], tick["mapping"]) == ("CMC_Matrix", "module")
assert typ(result, "MATRIX")["inherits"] == ["*"]
assert next(b for b in result["binaries"] if b["sha256"] == "b" * 64)["host_family"] == "Piklib 8"
def test_builtin_statements_are_read_from_the_parser(tmp_path):
parser = tmp_path / "core/src/pl/genschu/bloomooemulator/interpreter/parser"
parser.mkdir(parents=True)
(parser / "CodeParser.java").write_text('''class CodeParser {
private static ASTNode dispatchSpecialCall(String name, SourceSpan argsText) {
return switch (name) {
case "INT", "BOOL" -> new VarDefNode(name);
case "IF" -> buildIf(args); // "case" in a comment: "FAKE" ->
case "FOR" -> throw new ParseException("@FOR not implemented yet", location);
default -> throw new ParseException("Unknown special call: @" + name, location);
};
}
}''')
emu = emulator(tmp_path)
builtins = emu["types"]["@"]["methods"]
assert set(builtins) == {"INT", "BOOL", "IF", "FOR"}
assert builtins["FOR"]["status"] == "stub_candidate"
assert builtins["IF"]["status"] == "registered"
result = build_tracker([factory_snapshot()], emu)
assert row(result, "@", "IF")["status"] == "registered"
assert row(result, "@", "MSGBOX")["status"] == "missing"
def test_local_registration_of_a_base_verb_is_flagged(tmp_path):
snap = factory_snapshot()
emu = emulator(tmp_path)
emu["types"]["STRING"] = {"mapping_notes": [], "methods": {
"CLONE": {"status": "registered", "notes": [], "source": {"owner": "STRING"}}}}
result = build_tracker([snap], emu)
assert any("metoda bazowa (*)" in n for n in row(result, "STRING", "CLONE")["notes"])
def test_unknown_hash_not_fabricated_and_method_ids_are_binary_local(tmp_path):
a, b = native(), native(None)
b.raw["method_dispatch"][0]["impl_addr"] = "0x10009999"
result = build_tracker([a,b], emulator(tmp_path))
assert {o["impl_addr"] for o in row(result)["original"]} == {"0x10001000", "0x10009999"}
assert any(b["sha256"] is None and b["id"].startswith("snapshot:") for b in result["binaries"])
def test_review_stales_on_source_or_commit_change_and_covers_only_one_binary(tmp_path):
emu = emulator(tmp_path)
r = review(emu)
assert row(build_tracker([native()], emu, [r]))["verification"] == "asm_reviewed"
changed = deepcopy(emu)
changed["source_tree_sha256"] = "b" * 64 # includes helper changes, not just lambda
assert row(build_tracker([native()], changed, [r]))["verification"] == "stale"
changed = deepcopy(emu)
changed["commit"] = "d" * 40
assert row(build_tracker([native()], changed, [r]))["verification"] == "stale"
multiple = build_tracker([native(),native("c"*64)], emu, [r])
assert row(multiple)["verification"] == "unverified"
assert row(multiple)["verified_variants"] == 1
def test_review_without_required_anchors_rejected(tmp_path):
path = tmp_path / "reviews.json"
path.write_text(json.dumps({"schema":"tracker-reviews/1", "reviews":[{"type":"BOOLEAN"}]}))
with pytest.raises(ValueError): load_reviews(path)
emu = emulator(tmp_path / "repo")
path.write_text(json.dumps({"schema":"tracker-reviews/1", "reviews":[review(emu),review(emu)]}))
with pytest.raises(ValueError, match="Duplicate"): load_reviews(path)
def test_kolorowanka_registration_is_not_behavior_verification(tmp_path):
snap = Snapshot.load(str(Path(__file__).parents[1] / "snapshots/kolorowanka.snapshot.json"))
result = build_tracker([snap], emulator(tmp_path))
t = next(t for t in result["types"] if t["name"] == "KOLOROWANKA")
assert len(t["methods"]) == 23
assert all(m["verification"] == "unverified" for m in t["methods"])
assert row(result,"KOLOROWANKA","GETENDCOLOR")["original"][0]["evidence_ids"]
def test_duplicate_native_name_and_id_preserved(tmp_path):
snap = native()
snap.raw["methods"].extend([
{"owner": "CMC_Bool", "name": "SET", "id": 3},
{"owner": "CMC_Bool", "name": "OTHER", "id": 3},
])
result = build_tracker([snap], emulator(tmp_path))
assert {o["method_id"] for o in row(result)["original"]} == {1, 3}
assert len(row(result)["notes"]) == 2
assert len(row(result, method="OTHER")["notes"]) == 1
def test_world_snapshot_joins_and_keeps_registration_ambiguity(tmp_path):
snap = Snapshot.load(str(Path(__file__).parents[1] / "snapshots/world.snapshot.json"))
result = build_tracker([snap], emulator(tmp_path))
world = next(t for t in result["types"] if t["name"] == "WORLD")
assert len(world["methods"]) == 66
position = row(result, "WORLD", "SETPOSITION")
assert {o["method_id"] for o in position["original"]} == {24, 43}
assert len(position["notes"]) == 2
assert result["binaries"][0]["limitations"]
def test_known_class_aliases_do_not_create_false_missing_types(tmp_path):
snap = Snapshot({"binary": {"sha256": SHA}, "types": [
{"script_name": "CANVAS_OBSERVER", "cpp_class": None},
{"script_name": "GROUP", "cpp_class": None}], "methods": [
{"owner": "CMC_CanvasObserver", "name": "REFRESH", "id": None},
{"owner": "CMC_Groupped", "name": "ADD", "id": None}]})
result = build_tracker([snap], emulator(tmp_path))
assert row(result, "CANVAS_OBSERVER", "REFRESH")["original"][0]["mapping"] == "inferred"
assert row(result, "GROUP", "ADD")["original"]
assert not {"CANVASOBSERVER", "GROUPPED"} & {t["name"] for t in result["types"]}
def test_api_configuration_and_download(tmp_path, monkeypatch):
from fastapi.testclient import TestClient
from ams.api.app import create_app
monkeypatch.delenv("AMS_EMULATOR_ROOT", raising=False)
monkeypatch.delenv("AMS_TRACKER_REVIEWS", raising=False)
monkeypatch.delenv("AMS_TRACKER_SNAPSHOTS", raising=False)
client = TestClient(create_app("sqlite:///" + str(tmp_path / "test.db")))
assert client.get("/tracker").status_code == 503
emulator(tmp_path / "repo")
monkeypatch.setenv("AMS_EMULATOR_ROOT", str(tmp_path / "repo"))
snaps = tmp_path / "snapshots"
snaps.mkdir()
(snaps / "test.snapshot.json").write_text(json.dumps(native().raw))
monkeypatch.setenv("AMS_TRACKER_SNAPSHOTS", str(snaps))
response = client.get("/tracker?download=1")
assert response.status_code == 200
assert "attachment" in response.headers["content-disposition"]
assert response.json()["schema"] == "tracker/1"
assert client.get("/ui/tracker.html").status_code == 200
def test_shared_runner_methods_follow_per_type_verdicts(tmp_path):
emu = emulator(tmp_path)
emu["types"]["INTEGER"] = {"mapping_notes": [], "methods": {
"UPPER": {"status": "registered", "notes": [], "source": {"owner": "INTEGER"}}}}
result = build_tracker([factory_snapshot()], emu)
assert row(result, "STRING", "UPPER")["original"]
upper = row(result, "INTEGER", "UPPER") # registered by the emulator, skipped by the original
assert upper["original"] == [] and any("obj.getType()" in n for n in upper["notes"])
assert row(result, "STRING", "ADD")["signatures"] == ["(int) → copy"]
assert any("bez efektu" in n for n in row(result, "INTEGER", "ADD")["notes"])
assert row(result, "INTEGER", "ADD")["original"][0]["per_type"] == "trivial_virtual"
def test_class_constructor_runners_map_piklib61_types(tmp_path):
snap = Snapshot({"binary": {"name": "p61.dll", "sha256": SHA},
"types": [{"script_name": "INTEGER", "cpp_class": "CMC_Behaviour"}, # Pinokio's factory misparse
{"script_name": "CONDITION", "cpp_class": None}],
"methods": [{"owner": "CMC_Variable", "runner": "CMC_Variable_Runner", "name": "inc", "id": None},
{"owner": "CMC_BasicCondition", "runner": "CMC_BasicCondition_Runner", "name": "check", "id": None},
{"owner": "CMC_Behaviour", "runner": "CMC_Behaviour_Runner", "name": "run", "id": None}],
"field_inheritance": [{"class": "CMC_Integer", "base_class": "CMC_Variable"},
{"class": "CMC_Condition", "base_class": "CMC_BasicCondition"}],
"runner_map": {"by_class": [{"class": "CMC_Variable", "runner": "CMC_Variable_Runner"},
{"class": "CMC_Behaviour", "runner": "CMC_Behaviour_Runner"},
{"class": "CMC_BasicCondition", "runner": "CMC_BasicCondition_Runner"}]}})
result = build_tracker([snap], emulator(tmp_path))
assert row(result, "INTEGER", "INC")["original"][0]["mapping"] == "class_constructor"
assert row(result, "CONDITION", "CHECK")["original"]
assert "RUN" not in {m["name"] for m in typ(result, "INTEGER")["methods"]}
assert not {"VARIABLE", "BASICCONDITION"} & {t["name"] for t in result["types"]}
def test_events_per_type_and_emulator_signal_literals(tmp_path):
root = tmp_path
variables = root / "core/src/pl/genschu/bloomooemulator/interpreter/variable"
variables.mkdir(parents=True)
(variables / "Variable.java").write_text('interface Variable { void s() { emit("ONSIGNAL"); } }')
(variables / "IntegerVariable.java").write_text('''record IntegerVariable() {
VariableType type() { return VariableType.INTEGER; }
void set() { emitSignal("ONCHANGED"); } // emitSignal("ONDONE") in a comment does not count
}''')
engine = root / "core/src/pl/genschu/bloomooemulator/engine"
engine.mkdir(parents=True)
(engine / "Game.java").write_text('class Game { void tick() { emit("ONINIT"); } }')
emu = scan_emulator(root)
assert emu["signals"] == {
"*": {"ONSIGNAL": [{"path": "core/src/pl/genschu/bloomooemulator/interpreter/variable/Variable.java", "line": 1}]},
"INTEGER": {"ONCHANGED": [{"path": "core/src/pl/genschu/bloomooemulator/interpreter/variable/IntegerVariable.java", "line": 3}]},
"engine": {"ONINIT": [{"path": "core/src/pl/genschu/bloomooemulator/engine/Game.java", "line": 1}]}}
vftable = factory_snapshot()
vftable.raw["type_events"] = [{"type": "INTEGER", "name": n, "order": i}
for i, n in enumerate(["ONINIT", "ONDONE", "ONSIGNAL", "ONCHANGED"])]
classes = Snapshot({"binary": {"name": "p61.dll", "sha256": "b" * 64},
"types": [{"script_name": "STRING", "cpp_class": None}],
"events": [{"owner": "CMC_Variable", "name": "ONCHANGED", "order": 0}],
"field_inheritance": [{"class": "CMC_String", "base_class": "CMC_Variable"}]})
result = build_tracker([vftable, classes], emu)
status = {e["name"]: e["status"] for e in typ(result, "INTEGER")["events"]}
assert status == {"ONINIT": "engine_literal", "ONDONE": "not_found", "ONSIGNAL": "emitted_base",
"ONCHANGED": "emitted"}
assert [e["name"] for e in typ(result, "STRING")["events"]] == ["ONCHANGED"] # via CMC_Variable
assert result["summary"]["event_status"]["not_found"] >= 1
def test_fields_per_type_and_emulator_property_literals(tmp_path):
root = tmp_path
variables = root / "core/src/pl/genschu/bloomooemulator/interpreter/variable"
variables.mkdir(parents=True)
(variables / "Variable.java").write_text(
'interface Variable { void r(Context c) { c.getAttributeInHierarchy(name(), "TOINI"); } }')
(variables / "TextVariable.java").write_text('''record TextVariable() {
VariableType type() { return VariableType.TEXT; }
void load(Context context) { context.attributes().get(name, "RECT"); log("FONT"); }
}''')
loader = root / "core/src/pl/genschu/bloomooemulator/loader"
loader.mkdir(parents=True)
(loader / "CNVParser.java").write_text('''class CNVParser {
private Variable createVariable(String type, String objectName, Map<String, String> properties) {
return switch (type) {
case "TIMER" -> new TimerVariable(properties.get(objectName + ":ELAPSE"));
case "INTEGER", "INT" -> make(properties.get(objectName + ":VALUE"));
default -> null;
};
}
void other(String n, Map<String, String> p) { p.get(n + ":PRIORITY"); }
}''')
emu = scan_emulator(root)
props = {scope: sorted(v) for scope, v in emu["properties"].items()}
assert props == {"*": ["TOINI"], "TEXT": ["RECT"], "TIMER": ["ELAPSE"], "INTEGER": ["VALUE"],
"engine": ["PRIORITY"]}
snap = Snapshot({"binary": {"name": "p8.dll", "sha256": SHA},
"types": [{"script_name": "TEXT", "cpp_class": "CMC_Text"}, {"script_name": "INTEGER", "cpp_class": None}],
"type_fields": [{"type": "TEXT", "name": n, "value_types": ["string"], "order": i}
for i, n in enumerate(["RECT", "FONT", "PRIORITY"])],
"fields": [{"owner": "CMC_Variable", "name": "TOINI", "type": "bool", "order": 0},
{"owner": "CMC_Integer", "name": "VALUE", "type": "int", "order": 0}],
"field_inheritance": [{"class": "CMC_Integer", "base_class": "CMC_Variable"}]})
result = build_tracker([snap], emu)
assert {f["name"]: f["status"] for f in typ(result, "TEXT")["fields"]} == {
"RECT": "read", "FONT": "not_found", "PRIORITY": "engine_literal"}
integer = {f["name"]: f for f in typ(result, "INTEGER")["fields"]} # class chain, base first
assert [f["name"] for f in typ(result, "INTEGER")["fields"]] == ["TOINI", "VALUE"]
assert integer["TOINI"]["status"] == "read_base" and integer["VALUE"]["value_types"] == ["int"]
def test_name_dispatch_rows_join_methods_without_ids(tmp_path):
snap = Snapshot({"binary": {"name": "p61.dll", "sha256": SHA},
"types": [{"script_name": "ANIMO", "cpp_class": None}],
"methods": [{"owner": "CMC_Animo", "runner": "CMC_Animo_Runner", "name": "setPosition", "id": None}],
"method_dispatch": [{"owner": "CMC_Animo", "runner": "CMC_Animo_Runner", "id": None, "name": "SETPOSITION",
"dispatch": "name", "impl_addr": "0x10027ff0", "params": [
{"index": 0, "types": ["int"]}, {"index": 1, "types": ["int"]}],
"variadic": False, "returns": []}]})
result = build_tracker([snap], emulator(tmp_path))
entry = row(result, "ANIMO", "SETPOSITION")
assert entry["original"][0]["impl_addr"] == "0x10027ff0"
assert entry["signatures"] == ["(int, int) → —"]
def test_roadmap_lists_gaps_with_engine_families(tmp_path):
from ams.roadmap import render
tracker = {"emulator": {"commit": "f" * 40, "dirty": False},
"binaries": [{"id": "a", "family": "Piklib 8"}, {"id": "b", "family": "BlooMoo"}],
"types": [{"name": "VECTOR", "methods": [
{"name": "NORMALIZE", "status": "missing", "original": [{"binary_id": "a"}, {"binary_id": "b"}],
"signatures": ["() → —"]},
{"name": "GET", "status": "registered", "original": [{"binary_id": "a"}]},
{"name": "LEN", "status": "missing", "original": [{"binary_id": "b"}], "signatures": []}],
"events": [{"name": "ONINIT", "status": "engine_literal", "original": ["a"]}],
"fields": [{"name": "SIZE", "status": "not_found", "original": ["a", "b"], "value_types": ["int"]}]},
{"name": "INSTANCE", "methods": [{"name": "X", "status": "missing", "original": [{"binary_id": "a"}]}]}]}
text = render(tracker)
assert "| VECTOR | 1 / 3 | 2 | 0 | 0 / 1 | 1 / 1 |" in text
assert "`NORMALIZE` () → — (8, BM); `LEN` (BM)" in text # wider presence first
assert "`SIZE` int (8, BM)" in text and "INSTANCE" not in text