"""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()