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>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
835cd4f729
commit
95ad4edb5c
@@ -0,0 +1,91 @@
|
|||||||
|
"""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()
|
||||||
@@ -368,3 +368,21 @@ def test_name_dispatch_rows_join_methods_without_ids(tmp_path):
|
|||||||
entry = row(result, "ANIMO", "SETPOSITION")
|
entry = row(result, "ANIMO", "SETPOSITION")
|
||||||
assert entry["original"][0]["impl_addr"] == "0x10027ff0"
|
assert entry["original"][0]["impl_addr"] == "0x10027ff0"
|
||||||
assert entry["signatures"] == ["(int, int) → —"]
|
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
|
||||||
|
|||||||
Reference in New Issue
Block a user