feat(usage): count how game scripts use each type and rank roadmap gaps by it

ams.usage reads game discs with 7-Zip (bsdtar misses the files on some
images), decrypts CNV/DEF/CLASS like the emulator's ScriptDecypher and
counts method calls, event handlers, properties and objects per declared
type. CLONE copies, database cursors, global objects, CLASS instances and
string-named targets are resolved; the rest stays per method name.

ams.roadmap --usage orders every gap by the games and script places that
use it, adds a priority table and lists direct usage the original's known
API does not explain.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Patryk Gensch
2026-10-28 20:37:10 +01:00
co-authored by Claude Opus 5.5
parent 96c39d542a
commit ebbeeea144
3 changed files with 453 additions and 25 deletions
+90
View File
@@ -0,0 +1,90 @@
from ams.roadmap import render
from ams.usage import decode, scan
def encrypt(text: str, movement: int, direction: str = "C") -> bytes:
"""Inverse of ScriptDecypher, for tests: shift back, a newline becomes <E>, layout CR/LF added."""
sign, out, step = -1 if direction == "D" else 1, bytearray(), 0
for byte in text.encode("windows-1250"):
if byte == 10:
out += b"<E>\r\n"
continue
step = step % movement + 1
magnitude = (step + 1) // 2
out.append((byte - (-magnitude if step % 2 else magnitude) * sign) & 0xFF)
return b"{<%s:%d>}" % (direction.encode(), movement) + bytes(out)
def test_decode_inverts_both_cipher_directions_and_reads_plain_scripts():
text = "OBJECT=ŻABA\nŻABA:TYPE=ANIMO\n"
assert decode(encrypt(text, 6)) == text
assert decode(encrypt(text, 3, "D")) == text
assert decode(text.encode("windows-1250")) == text
SCENE = """# comment
OBJECT=ANN
ANN:TYPE=ANIMO
ANN:FILENAME=X.ANN
ANN:ONFINISHED^PLAY={ANN^HIDE();}
OBJECT=SNAME
SNAME:TYPE=STRING
SNAME:VALUE=ANN
OBJECT=CLS
CLS:TYPE=CLASS
OBJECT=BEH
BEH:TYPE=BEHAVIOUR
BEH:CODE={ANN^PLAY("X");*SNAME^SHOW();@IF(B,"_","TRUE","BEH","");RANDOM^GET(5);$1^STOP();
CLS^NEW("INST");INST^FOO();ANN_2^SETFRAME(1);BOOM^PLAY();}
"""
OTHER = """OBJECT=ANN
ANN:TYPE=IMAGE
OBJECT=X
X:TYPE=BEHAVIOUR
X:CODE={ANN^SHOW();*SNAME^SHOW();}
"""
THIRD = "OBJECT=Y\nY:TYPE=BEHAVIOUR\nY:CODE={ANN^GETWIDTH();}\n"
def test_scan_attributes_calls_events_and_fields_to_declared_types():
usage = scan({"a.cnv": SCENE, "b.cnv": OTHER, "c.cnv": THIRD})
assert usage["methods"]["ANIMO"] == {"HIDE": 1, "PLAY": 1, "SETFRAME": 1} # ANN_2: a CLONE copy
assert usage["methods"]["IMAGE"] == {"SHOW": 1} # the same file's declaration wins
assert usage["dynamic"] == {"ANIMO": {"SHOW": 1}, "IMAGE": {"SHOW": 1}} # SNAME holds "ANN"
assert usage["methods"]["@"] == {"IF": 1} and usage["methods"]["RAND"] == {"GET": 1}
assert usage["methods"]["INSTANCE"] == {"FOO": 1} and usage["methods"]["CLASS"] == {"NEW": 1}
assert usage["events"] == {"ANIMO": {"ONFINISHED": 1}}
assert usage["fields"]["ANIMO"] == {"FILENAME": 1} and usage["fields"]["STRING"] == {"VALUE": 1}
assert usage["unresolved"]["calls"] == {"GETWIDTH": 1, "PLAY": 1, "STOP": 1}
assert usage["unresolved"]["reasons"] == {"ambiguous": 1, "parameter": 1, "undeclared": 1}
assert usage["objects"]["BEHAVIOUR"] == 3 and usage["files"] == 3
def build(title, family, **tables):
return {"title": title, "family": family, "objects": tables.pop("objects", {}),
"methods": {}, "dynamic": {}, "events": {}, "fields": {},
"unresolved": {"calls": {}, "reasons": {}, "targets": {}}, **tables}
def test_roadmap_orders_gaps_by_games_that_use_them():
tracker = {"emulator": {}, "binaries": [{"id": "a", "family": "Piklib 8"}],
"types": [{"name": "*", "methods": [{"name": "GETNAME", "status": "missing", "original": [{"binary_id": "a"}]}]},
{"name": "CANVAS_OBSERVER", "methods": [
{"name": "REDRAW", "status": "missing", "original": [{"binary_id": "a"}]},
{"name": "SAVE", "status": "missing", "original": [{"binary_id": "a"}]},
{"name": "ADD", "status": "registered", "original": [{"binary_id": "a"}]}],
"events": [{"name": "ONUPDATE", "status": "not_found", "original": ["a"]}], "fields": []}]}
usage = {"builds": [
build("Gra A", "Piklib 8", objects={"CANVASOBSERVER": 1},
methods={"CANVASOBSERVER": {"SAVE": 2, "ADD": 9, "PASTE": 1}}, dynamic={"CANVAS_OBSERVER": {"BLUR": 4}}),
build("Gra A", "Piklib 8", methods={"CANVAS_OBSERVER": {"SAVE": 3}}), # another release: counts once
build("Gra B", "BlooMoo", methods={"CANVAS_OBSERVER": {"SAVE": 1}}, events={"CANVAS_OBSERVER": {"ONUPDATE": 2}},
unresolved={"calls": {"GETNAME": 5}, "reasons": {}, "targets": {}}),
build("Gra C", "Piklib 5", methods={"CANVAS_OBSERVER": {"REDRAW": 7}})]} # not a tracked family
text = render(tracker, usage)
assert "3 wydań, 2 gier" in text
assert "`SAVE` (8) — gry: 2, miejsca: 4; `REDRAW` (8) — nieużywane" in text
assert "| CANVAS_OBSERVER | `SAVE` | metoda | 2 | 4 | 8 |" in text
assert "| * | `GETNAME` | metoda | 1 | 5 | 8 |" in text # unknown target, base method
assert "| CANVASOBSERVER | `PASTE` | metoda | 1 | 1 | 8 |" in text and "BLUR" not in text
assert "Obiekty w skryptach: 1 (gry: 1)." in text