From 597733d8d7a7a5367672ff50f898df8b1ad7f4c3 Mon Sep 17 00:00:00 2001 From: Patryk Gensch <43010113+patryk025@users.noreply.github.com> Date: Sat, 24 Oct 2026 19:49:26 +0200 Subject: [PATCH] feat: type_events in diff and tracker, joined with emulator signal literals Diff gains a type_events axis keyed by (script type, event). The tracker lists each type's original events (vftable list, or the nearest class list up the constructor chain for Piklib 6.1) and where the emulator names them: the type's class, Variable.java or other engine code. Co-Authored-By: Claude Opus 5.5 --- README.md | 4 +- ams/api/static/tracker.js | 3 +- ams/diff.py | 4 ++ ams/render.py | 3 ++ ams/snapshot.py | 5 +++ ams/tracker.py | 79 +++++++++++++++++++++++++++++++++++++-- docs/tracker.md | 1 + tests/test_diff.py | 11 ++++++ tests/test_tracker.py | 32 ++++++++++++++++ 9 files changed, 135 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index ba6cc68..07231fa 100644 --- a/README.md +++ b/README.md @@ -112,7 +112,7 @@ bywają aliasami (ICF skleja identyczne ciała), więc liczy się adres i każda |----|-------------------|--------| | Typy | `CMC_ObjectsContainer::resolve` (8.x/BlooMoo) lub `CMC_Scene::resolve` (Piklib 6.1/7.1): `operator==("NAME")` → `operator_new(SIZE)` → ctor | ✅ (8.x inline; 6.1 tag-based = nazwy bez ctora) | | Metody | `CMC_*_Runner::prepareMthHashSet`: `CInteger(id)` + `CStringHashCode("NAME")` + `CHashtable::put` | ✅ (+ `method_inheritance`) | -| Eventy | `CMC_*::getBehavioursList`: lista literałów `CXString` | ✅ (lista per klasa, bez dziedziczenia) | +| Eventy | `CMC_*::getBehavioursList`: lista literałów `CXString` | ✅ per klasa (`events`) i per typ (`type_events`: slot `getBehavioursList` z vtable typu, także klasy bez symboli) | | Pola (skryptowe) | ctory `CMC_*`: literały czytane przez `CMElement::getPropertyValue` → nazwa + typ pola (FPS, PRELOAD, VISIBLE…) | ✅ (+ `field_inheritance`) | | Layout C++ (bonus) | ctory `CMC_*`: store'y `this+offset` przez P-code (rozmyte, `is_vtable`) | ✅ pod `struct_layout` | | Ciała metod | `CMC_*_Runner::run`: `switch(id)` → per case kotwice CALL (`Klasa::metoda` / `vtbl+0xNN`), rozwinięcie wrapperów | ✅ pod `method_dispatch` (id→`impl_addr`+`calls`) | @@ -277,4 +277,4 @@ A/B i odpalający porównanie). `schema_version`, `binary{name,sha256,engine,compiler,factory_addr}`, oraz listy `types` / `methods` / `events` / `fields`. Diff = operacje na zbiorach dwóch snapshotów. Od wersji 5: `runner_map` (`by_type_id` / `by_class`, sloty `CMC_Runner`), `types[].type_id` -i `vftable`, a w `method_dispatch` fakty z ciała metody. +i `vftable`, a w `method_dispatch` fakty z ciała metody. Od wersji 6: `type_events`. diff --git a/ams/api/static/tracker.js b/ams/api/static/tracker.js index 452b9bf..54535a4 100644 --- a/ams/api/static/tracker.js +++ b/ams/api/static/tracker.js @@ -1,4 +1,5 @@ 'use strict'; +const EVENT_STATUS={emitted:'emitowany w klasie typu',emitted_base:'emitowany w Variable',engine_literal:'literał w kodzie silnika',not_found:'brak literału w emulatorze'}; const MAPPING={explicit:'Jawne (klasa C++ z fabryki)',runner_factory:'CMC_RunnerFactory (typ → runner)',class_constructor:'Runner tworzony w konstruktorze klasy',inferred:'Wywnioskowane z nazwy'}; const $ = id => document.getElementById(id); const labels = {missing:'Brak rejestracji',registered:'Zarejestrowana',stub_candidate:'Podejrzenie stubu',partial:'Częściowa',implemented:'Zaimplementowana',unverified:'Niezweryfikowana',asm_reviewed:'Przegląd ASM',runtime_tested:'Test zachowania',stale:'Dowód wymaga aktualizacji'}; @@ -23,7 +24,7 @@ function render(){ $('stats').replaceChildren(stat(methods.length,'par typ / metoda (także dziedziczone)'),stat(methods.filter(registered).length,'zarejestrowanych w emulatorze'),stat(methods.filter(m=>m.status==='implemented').length,'oznaczonych jako zaimplementowane'),stat(methods.filter(reviewed).length,'z aktualnym dowodem ASM / testu')); $('types').replaceChildren(); for(const t of groups){const b=el('button',undefined,'type');b.type='button';b.setAttribute('aria-pressed',String(selected===t.name));const n=t.methods.length,r=t.methods.filter(registered).length,v=t.methods.filter(reviewed).length;b.append(el('strong',typeName(t.name)),el('small',n ? `${n} metod · ${r} rejestracji · ${v} dowodów` : 'Metody nierozpoznane — typ wykryty'));for(const [amount,cls,title] of [[r,'','Rejestracja'],[v,'review','Weryfikacja']]){const bar=el('div',undefined,'bar '+cls);bar.title=`${title}: ${amount} / ${n}`;const fill=el('i');fill.style.width=`${n ? 100*amount/n : 0}%`;bar.append(fill);b.append(bar);}b.onclick=()=>{selected=selected===t.name?null:t.name;render();};$('types').append(b);} - const chosen=data.types.find(t=>t.name===selected);const typeNotes=[...(chosen?.inherits||[]).map(base=>`Dziedziczy metody bazowe zakresu ${base}.`),...(chosen?.mapping_notes||[])];$('type-notes').hidden=!typeNotes.length;$('type-notes').textContent=typeNotes.map(note=>typeof note==='string'?note:JSON.stringify(note)).join('\n');$('methods-heading').textContent=selected?typeName(selected):'Wszystkie metody';$('count').textContent=`${methods.length} pozycji`;$('rows').replaceChildren(); + const chosen=data.types.find(t=>t.name===selected);const typeNotes=[...(chosen?.inherits||[]).map(base=>`Dziedziczy metody bazowe zakresu ${base}.`),...(chosen?.events?.length?['Eventy w oryginale: '+chosen.events.map(e=>`${e.name} (${EVENT_STATUS[e.status]||e.status})`).join(', ')]:[]),...(chosen?.mapping_notes||[])];$('type-notes').hidden=!typeNotes.length;$('type-notes').textContent=typeNotes.map(note=>typeof note==='string'?note:JSON.stringify(note)).join('\n');$('methods-heading').textContent=selected?typeName(selected):'Wszystkie metody';$('count').textContent=`${methods.length} pozycji`;$('rows').replaceChildren(); for(const t of active)for(const m of t.methods){const tr=el('tr'),name=el('td');name.append(el('small',typeName(t.name)),el('strong',m.name));const s=el('td'),v=el('td');s.append(badge(m.status));v.append(badge(m.verification));const found=original(m);const availability=el('td',found.length?`Wykryta · ${new Set(found.map(o=>o.binary_id)).size} wariantów`:'Nieustalone');const action=el('td'),b=el('button','Dowody ↗','quiet');b.setAttribute('aria-label',`Dowody ${t.name}.${m.name}`);b.onclick=()=>detail(t,m);action.append(b);tr.append(name,s,v,availability,action);$('rows').append(tr);} $('empty').hidden=methods.length>0;$('empty').textContent=chosen && !chosen.methods.length ? 'Typ został wykryty, ale metody nie zostały jeszcze rozpoznane. Brak wpisów nie oznacza braku API.' : 'Brak metod dla wybranych filtrów.'; } diff --git a/ams/diff.py b/ams/diff.py index b644ada..5ea6f3d 100644 --- a/ams/diff.py +++ b/ams/diff.py @@ -118,6 +118,8 @@ def compute_diff(old: Snapshot, new: Snapshot) -> dict[str, Any]: "types": keyed_diff(old.types, new.types, _type_key, ["cpp_class", "object_size"]), "methods": keyed_diff(old.methods, new.methods, _owner_name_key, ["id"]), "events": keyed_diff(old.events, new.events, _owner_name_key, ["order"]), + "type_events": keyed_diff(old.type_events, new.type_events, + lambda x: (x["type"], x["name"]), ["order"]), "fields": keyed_diff(old.fields, new.fields, _owner_name_key, ["type"]), "struct_layout": keyed_diff(old.struct_layout, new.struct_layout, _layout_key, ["size", "is_vtable"]), @@ -136,6 +138,8 @@ def _item_owner(axis: str, item: Item) -> str | None: return item.get("cpp_class") if axis in ("methods", "events", "fields", "struct_layout", "method_dispatch"): return item.get("owner") + if axis == "type_events": + return item.get("type") # script type name, e.g. --owner ANIMO if axis == "method_inheritance": return item.get("runner") if axis == "field_inheritance": diff --git a/ams/render.py b/ams/render.py index ab2d204..3c364e4 100644 --- a/ams/render.py +++ b/ams/render.py @@ -151,6 +151,9 @@ def render_text(diff: dict[str, Any], only: set[str] | None = None) -> str: if want("events") and not _is_empty(diff["events"]): _section_owned(out, "EVENTS", diff["events"], _fmt_event, lambda e: e["owner"], lambda e: e["name"]) + if want("events") and not _is_empty(diff.get("type_events", _EMPTY)): + _section_owned(out, "TYPE EVENTS", diff["type_events"], _fmt_event, + lambda e: e["type"], lambda e: e["name"]) if want("fields") and not _is_empty(diff["fields"]): _section_owned(out, "FIELDS", diff["fields"], _fmt_field, lambda f: f["owner"], lambda f: f["name"]) diff --git a/ams/snapshot.py b/ams/snapshot.py index 08ffbc8..baa7edf 100644 --- a/ams/snapshot.py +++ b/ams/snapshot.py @@ -35,6 +35,11 @@ class Snapshot: def events(self) -> list[dict]: return self.raw.get("events", []) + @property + def type_events(self) -> list[dict]: + """Events per script type, read through each type's own vftable (schema 6).""" + return self.raw.get("type_events", []) + @property def fields(self) -> list[dict]: return self.raw.get("fields", []) diff --git a/ams/tracker.py b/ams/tracker.py index 5e287f8..5481439 100644 --- a/ams/tracker.py +++ b/ams/tracker.py @@ -63,6 +63,32 @@ BUILTINS_DISPATCH = re.compile(r"\bdispatchSpecialCall\s*\([^)]*\)\s*\{") CASE_ARM = re.compile(r"\bcase\b([^;{}]*?)->|\bdefault\b\s*->") +SIGNAL_LITERAL = re.compile(r'"(ON[A-Z][A-Z_]*)"') +NOT_SIGNALS = {"ONEBREAK"} # the @ONEBREAK statement, not an event + + +def scan_signals(root: Path, source_root: Path, variable_root: Path) -> dict: + """Where the emulator names each event: {scope: {event: [source]}}. A `Variable.java` + file is that type's scope, Variable.java is `*`, any other file is `engine`. Only string + literals count (comments ignored); names built at runtime are invisible, so absence is + "no literal found", never proof that an event is missing.""" + scopes = {} + for path, text in sorted((p, p.read_text(encoding="utf-8")) for p in source_root.rglob("*.java")): + scope = "engine" + if path.parent == variable_root and path.name.endswith("Variable.java"): + if path.name == "Variable.java": + scope = "*" + else: + match = re.search(r"return\s+VariableType\.([A-Z_]+)\s*;", code_mask(text)) + scope = canonical(match[1]) if match else "engine" + for token in JAVA_TOKENS.finditer(text): + literal = SIGNAL_LITERAL.fullmatch(token.group()) + if literal and literal[1] not in NOT_SIGNALS: + scopes.setdefault(scope, {}).setdefault(literal[1], []).append( + {"path": str(path.relative_to(root)), "line": text.count("\n", 0, token.start()) + 1}) + return scopes + + def scan_builtins(root: Path, source_root: Path) -> dict | None: """`@IF`, `@LOOP`, ... are parsed by CodeParser.dispatchSpecialCall, not registered as MethodSpec: each `case "NAME", ... ->` arm of its switch is one built-in statement.""" @@ -152,7 +178,7 @@ def scan_emulator(root: Path) -> dict: builtins = scan_builtins(root, source_root) if builtins is not None: types["@"] = builtins - return {"root": str(root), "commit": _git(root, "rev-parse", "HEAD"), + return {"root": str(root), "signals": scan_signals(root, source_root, variable_root), "commit": _git(root, "rev-parse", "HEAD"), "dirty": bool(_git(root, "status", "--porcelain")), "source_tree_sha256": tree.hexdigest(), "types": types, "warnings": warnings} @@ -199,6 +225,35 @@ def _constructor_runner(name, cpp_class, class_runner, bases, known_classes): return None +def script_events(snap: Snapshot) -> dict[str, list[str]]: + """Script type -> ordered event names for one binary. `type_events` (each type's own + vftable, schema 6) wins; otherwise the class list of the nearest class up this snapshot's + constructor chain that has one (INTEGER -> CMC_Variable).""" + out = {} + for e in sorted(snap.type_events, key=lambda e: e["order"]): + out.setdefault(canonical(e["type"]), []).append(e["name"].upper()) + by_class = {} + for e in sorted(snap.events, key=lambda e: e.get("order") or 0): + by_class.setdefault(e["owner"], []).append(e["name"].upper()) + bases = {e["class"]: e["base_class"] for e in snap.field_inheritance} + known = set(by_class) | set(bases) | set(bases.values()) + for t in snap.types: + name = canonical(t["script_name"]) + if name in out: + continue + cls = t.get("cpp_class") if t.get("cpp_class") != "CMC_Behaviour" or name == "BEHAVIOUR" else None + if not cls: + candidates = [c for c in known if owner_name(c) == name] + cls = candidates[0] if len(candidates) == 1 else None + seen = set() + while cls and cls not in seen and cls not in by_class: + seen.add(cls) + cls = bases.get(cls) + if cls in by_class: + out[name] = by_class[cls] + return out + + def script_owners(snap: Snapshot, owners) -> dict[str, tuple[str, str]]: """Script scope -> (method owner, provenance) for one binary. @@ -291,6 +346,11 @@ def build_tracker(snapshots: list[Snapshot], emulator: dict, reviews: list[dict] parents = defaultdict(list) for edge in snap.method_inheritance: parents[edge["runner"].removesuffix("_Runner")].append(edge["base_runner"].removesuffix("_Runner")) + for name, names in script_events(snap).items(): + events = type_row(name).setdefault("events", {}) + for order, event in enumerate(names): + events.setdefault(event, {"name": event, "order": order, "original": [], "emulator": [], + "status": "not_found"})["original"].append(bid) mappings = script_owners(snap, owners) for t in snap.types: row = type_row(canonical(t["script_name"])) @@ -369,6 +429,13 @@ def build_tracker(snapshots: list[Snapshot], emulator: dict, reviews: list[dict] if row is not None: row["notes"].append(f"Oryginał ({len(binaries_)} binarek) pomija tę metodę dla tego typu: " "warunek obj.getType() we wspólnym runnerze.") + signals = emulator.get("signals", {}) + for name, t in rows.items(): + for event, row in t.get("events", {}).items(): + own, base, engine = (signals.get(scope, {}).get(event, []) for scope in (name, "*", "engine")) + row["emulator"] = own + base + engine + row["status"] = ("emitted" if own else "emitted_base" if base + else "engine_literal" if engine else "not_found") base_verbs = {m for m, row in rows.get(BASE_SCOPE, {}).get("methods", {}).items() if row["original"]} for name, t in rows.items(): for method, row in t["methods"].items(): @@ -407,17 +474,21 @@ def build_tracker(snapshots: list[Snapshot], emulator: dict, reviews: list[dict] t["mapping_notes"] = sorted(set(t["mapping_notes"])) if "inherits" in t: t["inherits"] = sorted(set(t["inherits"])) + t["events"] = sorted(t.get("events", {}).values(), key=lambda e: (e["order"], e["name"])) all_rows = [m for t in rows.values() for m in t["methods"]] - return {"schema": "tracker/1", "emulator": {k: v for k, v in emulator.items() if k not in ("types", "warnings")}, + all_events = [e for t in rows.values() for e in t["events"]] + return {"schema": "tracker/1", "emulator": {k: v for k, v in emulator.items() if k not in ("types", "warnings", "signals")}, "binaries": sorted(binaries, key=lambda b: (b["name"].lower(), b["id"])), "types": sorted(rows.values(), key=lambda t: t["name"]), "summary": {"types": len(rows), "methods": len(all_rows), "status": dict(Counter(m["status"] for m in all_rows)), - "verification": dict(Counter(m["verification"] for m in all_rows))}, + "verification": dict(Counter(m["verification"] for m in all_rows)), + "events": len(all_events), "event_status": dict(Counter(e["status"] for e in all_events))}, "warnings": warnings + ["Brak obserwacji w wariancie oznacza nieustalone, nie brak metody.", "Rejestracja Java nie dowodzi poprawności. Liczniki obejmują pary typ/metoda, także odziedziczone.", "Typ → runner pochodzi z CMC_RunnerFactory, gdy snapshot ma runner_map; inaczej z nazwy klasy (wnioskowane).", "Zakres * to metody bazowe CMC_Runner, wspólne dla każdego typu (pole inherits); nie są powielane przy typach.", - "Zakres @ to wbudowane instrukcje @IF/@LOOP/... (runner typu 0)."]} + "Zakres @ to wbudowane instrukcje @IF/@LOOP/... (runner typu 0).", + "Eventy: status emulatora to literał nazwy w kodzie (klasa typu / Variable / silnik); nazwy budowane dynamicznie nie są widoczne."]} def validate_review(review: dict) -> None: diff --git a/docs/tracker.md b/docs/tracker.md index 8217d12..ab6daaf 100644 --- a/docs/tracker.md +++ b/docs/tracker.md @@ -39,6 +39,7 @@ Atlas odczytuje snapshoty z dysku przy każdym pobraniu katalogu. Command Center Licznik to pary typ/metoda. Nie jest liczbą unikalnych ciał Java ani procentem zgodności całego silnika. Metody bazowe `CMC_Runner` (SEND, CLONE, …) są w zakresie `*` raz; typy wskazują go polem `inherits`. Zakres `@` to instrukcje `@IF`/`@LOOP`/… (runner typu 0), porównywane z `CodeParser.dispatchSpecialCall`. Typy bez rozpoznanych metod pozostają widoczne. Typ → runner pochodzi z `runner_map` snapshotu (fabryka w 7.1+, konstruktory klas w 6.1); bez niego z nazwy klasy, oznaczone jako wnioskowane. Metoda wspólnego runnera, którą oryginał pomija dla danego typu warunkiem `obj.getType()`, nie jest temu typowi przypisana; pusta implementacja wirtualna jest oznaczona jako brak efektu. Sygnatury (typy argumentów i wyniku) są odczytane z ciała metody i mogą być sumą wariantów (`int/string`). +Eventy typu pochodzą z jego vtable (`type_events`) albo z listy najbliższej klasy w łańcuchu konstruktorów. Po stronie emulatora liczy się literał nazwy: w klasie typu (`emitted`), w `Variable.java` (`emitted_base`), w innym kodzie bez przypisania do typu (`engine_literal`); `not_found` znaczy tylko, że literału nie ma. Alias `BOOL` jest łączony z `BOOLEAN`, `INT` z `INTEGER`; nazwy metod są normalizowane do uppercase. ID metody pozostaje lokalne dla konkretnej klasy i binarki. Relacje dziedziczenia pochodzą wyłącznie ze snapshotu, nie są zgadywane z innej wersji. Adapter rozpoznaje bieżący wzorzec rejestracji Java; nie jest ogólnym parserem języka Java. Komentarze i literały nie tworzą fałszywych wpisów, nawiasy są dopasowywane leksykalnie. Własne dispatchery `GROUP` / `INSTANCE` są oznaczone do przeglądu. Celowe no-op nie są automatycznie stubami. diff --git a/tests/test_diff.py b/tests/test_diff.py index 41ff21e..3fae834 100644 --- a/tests/test_diff.py +++ b/tests/test_diff.py @@ -128,3 +128,14 @@ def test_golden_pair_piklib_to_bloomoo(): disp_new = {(r["owner"], r["id"]): r for r in new.method_dispatch} assert disp_old[("CMC_Animo", 1)]["calls"][-1] == "vtbl+0xa0" assert disp_new[("CMC_Animo", 1)]["calls"][-1] == "vtbl+0xa0" + + +def test_type_events_diff_by_script_type(): + from ams.diff import compute_diff, filter_by_owner + from ams.snapshot import Snapshot + old = Snapshot({"type_events": [{"type": "MOVIE", "name": "ONSTARTED", "order": 3}]}) + new = Snapshot({"type_events": [{"type": "MOVIE", "name": "ONSTARTED", "order": 3}, + {"type": "MOVIE", "name": "ONFRAMEUPDATED", "order": 5}]}) + block = compute_diff(old, new)["type_events"] + assert [e["name"] for e in block["added"]] == ["ONFRAMEUPDATED"] and not block["removed"] + assert filter_by_owner(compute_diff(old, new), "MOVIE")["type_events"]["added"] diff --git a/tests/test_tracker.py b/tests/test_tracker.py index 182df56..1a0821e 100644 --- a/tests/test_tracker.py +++ b/tests/test_tracker.py @@ -281,3 +281,35 @@ def test_class_constructor_runners_map_piklib61_types(tmp_path): 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