psxrecomp/tools/codegen_audit_game.py

"""codegen_audit_game — audit generated C from the game full-function-emitter.

Sibling of `codegen_audit.py` (which audits BIOS strict-translator emit).
The two emit conventions differ enough that the audit passes themselves
diverge — see `docs/internal/audit_inventory.md` for the rationale.

Tomba / game-emit characteristics:
  - Direct function calls: `func_XXXXXXXX(cpu);`
  - Indirect dispatch:    `call_by_address(cpu, 0xXXXX);` or `call_by_address(cpu, cpu->gpr[N]);`
  - Tail call (same as BIOS): `cpu->pc = 0xXXXX; return;`
  - Branch cond:          `int _bc_XXXXXXXX = (expr);` (declare-and-assign in one line)
  - Block label:          `block_XXXXXXXX:`
  - Function def:          `void func_XXXXXXXX(CPUState* cpu) { ... }`

Audit passes:
  1. Direct-call resolution: every `func_XXXXXXXX(cpu)` call references a
     defined function (forward-declared in dispatch_c, defined in full_c).
  2. Literal `call_by_address(cpu, 0xXXXX)` target resolves to dispatch
     table.
  3. Indirect `call_by_address(cpu, cpu->gpr[N])` site distribution.
  4. Tail-call (`cpu->pc=X; return;`) target resolves to dispatch table.
  5. Branch-condition count & distribution per function.
  6. `goto block_X` target resolves to a labelled block in the same
     function (informational; cross-function gotos surface here).

Usage:
  python tools/codegen_audit_game.py --config /path/to/game.toml
"""
import re
import sys
from collections import Counter, defaultdict
from pathlib import Path

sys.path.insert(0, str(Path(__file__).parent))
import audit_config


# ── Patterns shared with codegen_audit.py (BIOS emit) ──────────────────
RE_TAIL_CALL = re.compile(r'cpu->pc = 0x([0-9A-Fa-f]+)u?;\s*return;')

# Game emit uses a switch/case dispatch table:
#   case 0xADDRu: func_ADDR(cpu); return 1;
# This is NOT the BIOS strict-translator's `{ 0xADDR, func_ADDR }` array.
RE_DISPATCH_TABLE_ENTRY = re.compile(
    r'case\s+0x([0-9A-Fa-f]+)u?\s*:\s*func_[0-9A-Fa-f]+\s*\(cpu\)'
)

# ── Patterns specific to game full-function-emitter ────────────────────
RE_DIRECT_CALL = re.compile(r'\bfunc_([0-9A-Fa-f]+)\(cpu\);')
RE_CALL_BY_ADDR_LIT = re.compile(
    r'call_by_address\(cpu,\s*0x([0-9A-Fa-f]+)u?\)\s*;'
)
RE_CALL_BY_ADDR_REG = re.compile(
    r'call_by_address\(cpu,\s*cpu->gpr\[(\d+)\]\)\s*;'
)
RE_BC_DECL = re.compile(r'\bint\s+_bc_([0-9A-Fa-f]+)\s*=\s*\(')
RE_FUNC_DEF = re.compile(r'^void\s+func_([0-9A-Fa-f]+)\s*\(CPUState\s*\*\s*cpu\s*\)\s*$', re.M)
RE_FUNC_FWD = re.compile(r'^extern\s+void\s+func_([0-9A-Fa-f]+)\s*\(', re.M)
RE_BLOCK_LABEL = re.compile(r'^(block_[0-9A-Fa-f]+):', re.M)
RE_GOTO_BLOCK = re.compile(r'\bgoto\s+(block_[0-9A-Fa-f]+)\s*;')


def main():
    cfg = audit_config.from_argv(sys.argv)
    print(f"# codegen audit (game emit): {cfg.name}")
    print(f"  full_c     = {cfg.full_c}")
    print(f"  dispatch_c = {cfg.dispatch_c}")
    print()

    if not cfg.full_c.exists():
        print(f"ERROR: full_c not found: {cfg.full_c}", file=sys.stderr)
        return 2
    if not cfg.dispatch_c.exists():
        print(f"ERROR: dispatch_c not found: {cfg.dispatch_c}", file=sys.stderr)
        return 2

    full_c = cfg.full_c.read_text(encoding="utf-8", errors="replace")
    dispatch_c = cfg.dispatch_c.read_text(encoding="utf-8", errors="replace")

    # ── 1. Direct-call resolution ──────────────────────────────────────
    defined_funcs = set(RE_FUNC_DEF.findall(full_c))
    forward_decls = set(RE_FUNC_FWD.findall(dispatch_c))
    declared_funcs = defined_funcs | forward_decls

    direct_calls = RE_DIRECT_CALL.findall(full_c)
    direct_targets = Counter(c.upper() for c in direct_calls)

    unresolved_calls = sorted(t for t in direct_targets if t not in
                              {f.upper() for f in declared_funcs})
    print(f"[1] direct func_XXXX(cpu) calls: {sum(direct_targets.values())} total, "
          f"{len(direct_targets)} unique targets")
    print(f"    defined functions in full_c: {len(defined_funcs)}")
    print(f"    forward decls in dispatch_c: {len(forward_decls)}")
    print(f"    unresolved direct-call targets: {len(unresolved_calls)}")
    for t in unresolved_calls[:25]:
        print(f"      func_{t}  ({direct_targets[t]} call site{'s' if direct_targets[t]!=1 else ''})")

    # ── 2. Literal call_by_address targets ─────────────────────────────
    # Targets in the declared code regions must resolve to the dispatch
    # table. Targets outside (RAM-loaded overlays, install-at-runtime
    # stubs) are handled by the runtime's dirty-RAM interpreter — expected
    # to be absent from the static dispatch table.
    def is_in_code(vaddr_normalized: int) -> bool:
        for r in cfg.regions:
            phys_lo = r.vaddr_base & cfg.kseg_mask
            phys_hi = phys_lo + (r.rom_end - r.rom_start)
            if phys_lo <= vaddr_normalized < phys_hi:
                return True
        return False

    cba_lits = RE_CALL_BY_ADDR_LIT.findall(full_c)
    cba_lit_set = set(cfg.normalize_addr(int(t, 16)) for t in cba_lits)
    table_entries = RE_DISPATCH_TABLE_ENTRY.findall(dispatch_c)
    table_set = set(cfg.normalize_addr(int(e, 16)) for e in table_entries)

    cba_in_code = {t for t in cba_lit_set if is_in_code(t)}
    cba_in_ram = cba_lit_set - cba_in_code

    cba_missing_in_code = sorted(cba_in_code - table_set)
    print(f"\n[2] literal call_by_address targets: {len(cba_lit_set)} unique, "
          f"{sum(1 for _ in cba_lits)} sites")
    print(f"    dispatch table size: {len(table_set)} entries")
    print(f"    targets in declared code regions: {len(cba_in_code)}")
    print(f"    targets in RAM (dirty-RAM interpreter domain): {len(cba_in_ram)}")
    print(f"    in-code targets MISSING from dispatch: {len(cba_missing_in_code)}")
    for m in cba_missing_in_code[:25]:
        cnt = sum(1 for t in cba_lits if cfg.normalize_addr(int(t, 16)) == m)
        print(f"      0x{m:08X}  ({cnt} site{'s' if cnt!=1 else ''})")

    # ── 3. Indirect call_by_address distribution ───────────────────────
    cba_regs = RE_CALL_BY_ADDR_REG.findall(full_c)
    print(f"\n[3] indirect call_by_address sites: {len(cba_regs)} total")
    print(f"    by register: {dict(Counter(cba_regs).most_common(8))}")

    # ── 4. Tail-call targets ───────────────────────────────────────────
    tail_calls = RE_TAIL_CALL.findall(full_c)
    tail_set = set(cfg.normalize_addr(int(t, 16)) for t in tail_calls)
    tail_missing = sorted(tail_set - table_set)
    print(f"\n[4] tail-call (cpu->pc=...; return;) targets: {len(tail_set)} unique, "
          f"{len(tail_calls)} sites")
    print(f"    tail-call targets MISSING from dispatch: {len(tail_missing)}")
    for m in tail_missing[:25]:
        cnt = sum(1 for t in tail_calls if cfg.normalize_addr(int(t, 16)) == m)
        print(f"      0x{m:08X}  ({cnt} site{'s' if cnt!=1 else ''})")

    # ── 5. Branch-condition population ─────────────────────────────────
    bc_decls = RE_BC_DECL.findall(full_c)
    print(f"\n[5] branch-condition declarations (`int _bc_X = (...);`): {len(bc_decls)}")

    # ── 6. goto block_X target resolution ──────────────────────────────
    labels = set(RE_BLOCK_LABEL.findall(full_c))
    gotos = RE_GOTO_BLOCK.findall(full_c)
    unresolved_gotos = sorted(set(gotos) - labels)
    print(f"\n[6] goto block_X targets: {len(gotos)} sites, {len(set(gotos))} unique")
    print(f"    block labels defined: {len(labels)}")
    print(f"    goto targets WITHOUT a matching block label: {len(unresolved_gotos)}")
    for g in unresolved_gotos[:25]:
        print(f"      {g}")

    # ── Summary ────────────────────────────────────────────────────────
    real_bugs = (
        len(unresolved_calls)        # direct call to undefined function
        + len(cba_missing_in_code)    # in-code literal call_by_address not in dispatch
        + len(tail_missing)           # tail call not in dispatch
        + len(unresolved_gotos)       # goto to undefined label
    )

    print(f"\n[summary] {cfg.name}")
    print(f"  unresolved direct calls           : {len(unresolved_calls)}")
    print(f"  in-code call_by_address misses    : {len(cba_missing_in_code)}")
    print(f"  RAM call_by_address (expected)    : {len(cba_in_ram)}")
    print(f"  tail-call misses                  : {len(tail_missing)}")
    print(f"  unresolved goto labels            : {len(unresolved_gotos)}")
    print(f"  total real-bug findings           : {real_bugs}")
    print(f"  STATUS                            : {'CLEAN' if real_bugs == 0 else 'ISSUES FOUND'}")

    return 0 if real_bugs == 0 else 1


if __name__ == "__main__":
    sys.exit(main())