Files
Aidem-Media-DLL-Analysis/ams/roadmap.py
T
Patryk GenschandClaude Opus 5.5 95ad4edb5c feat: ams.roadmap renders the emulator's gaps per scope from an Atlas export
Methods without a registration (with the original signature), emulator
stubs, and events/properties the emulator never names, each with the
engine families whose DLLs have it so core API sorts before late ones.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-24 20:35:42 +02:00

92 lines
5.2 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""Emulator roadmap from an Atlas export: what each script scope still lacks.
python -m ams.roadmap tracker.json -o docs/roadmap.md
Per scope: methods without a registration (with the signature read from the original),
emulator stubs, events and properties the emulator never names. Every item lists the engine
families whose DLLs have it - an item present in every family is core API, one present only
in BlooMoo is late. The report restates the tracker's limits: registration is not
correctness, and "never named" means no literal was found.
"""
from __future__ import annotations
import argparse
import json
from collections import Counter
from pathlib import Path
FAMILY_ORDER = ["Piklib 6.1", "Piklib 7.1", "Piklib 7.2", "Piklib 8", "BlooMoo"]
SHORT = {"Piklib 6.1": "6.1", "Piklib 7.1": "7.1", "Piklib 7.2": "7.2", "Piklib 8": "8", "BlooMoo": "BM"}
HIDDEN = {"INSTANCE"} # emulator helper, not an original type
def families(binary_ids, family_of) -> list[str]:
found = {family_of.get(b) for b in binary_ids} - {None}
return sorted(found, key=lambda f: (FAMILY_ORDER.index(f) if f in FAMILY_ORDER else len(FAMILY_ORDER), f))
def label(fams) -> str:
return ", ".join(SHORT.get(f, f) for f in fams) or "—"
def scope_gaps(scope: dict, family_of: dict) -> dict:
methods = scope["methods"]
original = [m for m in methods if m["original"]]
def item(name, binary_ids, detail=""):
return {"name": name, "families": families(binary_ids, family_of), "detail": detail}
missing = [item(m["name"], [o["binary_id"] for o in m["original"]], " / ".join(m.get("signatures") or []))
for m in original if m["status"] == "missing"]
stubs = [item(m["name"], [o["binary_id"] for o in m["original"]]) for m in methods if m["status"] == "stub_candidate"]
events = [item(e["name"], e["original"]) for e in scope.get("events", []) if e["status"] == "not_found"]
fields = [item(f["name"], f["original"], "/".join(f.get("value_types", [])))
for f in scope.get("fields", []) if f["status"] == "not_found"]
for items in (missing, events, fields): # widest presence first: core API before late additions
items.sort(key=lambda i: (-len(i["families"]), i["name"]))
return {"name": scope["name"], "methods_total": len(original),
"methods_registered": sum(m["status"] not in ("missing", "stub_candidate") for m in original),
"events_total": len(scope.get("events", [])), "fields_total": len(scope.get("fields", [])),
"missing": missing, "stubs": stubs, "events": events, "fields": fields}
def render(tracker: dict) -> str:
family_of = {b["id"]: b.get("family") for b in tracker["binaries"]}
scopes = [scope_gaps(t, family_of) for t in tracker["types"] if t["name"] not in HIDDEN]
scopes = [s for s in scopes if s["missing"] or s["stubs"] or s["events"] or s["fields"]]
scopes.sort(key=lambda s: (-(len(s["missing"]) + len(s["stubs"]) + len(s["events"]) + len(s["fields"])), s["name"]))
emulator = tracker.get("emulator", {})
counts = Counter(f for b in tracker["binaries"] for f in [b.get("family")] if f)
out = ["# Roadmapa emulatora", "",
"Wygenerowane przez `python -m ams.roadmap` z eksportu Atlasu "
f"(rewizja emulatora `{emulator.get('commit') or '?'}`"
f"{', niezacommitowane zmiany' if emulator.get('dirty') else ''}). Nie edytuj ręcznie.", "",
"Binarki: " + ", ".join(f"{SHORT.get(f, f)} × {n}" for f, n in sorted(counts.items(),
key=lambda kv: FAMILY_ORDER.index(kv[0]) if kv[0] in FAMILY_ORDER else 99)) + ".",
"Rejestracja nie oznacza poprawności; „brak literału” znaczy tylko, że nazwy nie ma w kodzie emulatora.",
"W nawiasie: rodziny silnika, w których DLL pozycja występuje.", "",
"| Zakres | Metody (zarejestrowane / w oryginale) | Bez rejestracji | Stuby | Eventy bez literału | Pola bez literału |",
"|---|---:|---:|---:|---:|---:|"]
for s in scopes:
out.append(f"| {s['name']} | {s['methods_registered']} / {s['methods_total']} | {len(s['missing'])} | "
f"{len(s['stubs'])} | {len(s['events'])} / {s['events_total']} | {len(s['fields'])} / {s['fields_total']} |")
for s in scopes:
out += ["", f"## {s['name']}"]
for title, items in (("Metody bez rejestracji", s["missing"]), ("Stuby w emulatorze", s["stubs"]),
("Eventy bez literału", s["events"]), ("Pola bez literału", s["fields"])):
if items:
out.append(f"- **{title}:** " + "; ".join(
f"`{i['name']}`" + (f" {i['detail']}" if i["detail"] else "") + f" ({label(i['families'])})"
for i in items))
return "\n".join(out) + "\n"
def main(argv=None):
parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument("tracker", type=Path, help="Atlas export (python -m ams.tracker ... --out)")
parser.add_argument("-o", "--out", type=Path, required=True)
args = parser.parse_args(argv)
args.out.write_text(render(json.loads(args.tracker.read_text(encoding="utf-8"))), encoding="utf-8")
if __name__ == "__main__":
main()