320 lines
No EOL
14 KiB
Python
320 lines
No EOL
14 KiB
Python
from __future__ import annotations
|
|
|
|
import unittest
|
|
|
|
from tools.poc_crusader_usecode_parser import (
|
|
classify_post_ret_metadata,
|
|
format_target_event_reference,
|
|
get_intrinsic_hints,
|
|
intrinsic_display_name,
|
|
render_pseudocode,
|
|
render_partially_structured_blocks,
|
|
render_structured_pseudocode,
|
|
try_decode_loop_selector,
|
|
validate_pseudocode_text,
|
|
)
|
|
|
|
|
|
class UsecodeStructuringTests(unittest.TestCase):
|
|
def test_post_ret_debug_symbols_are_classified_as_metadata(self) -> None:
|
|
body = bytes([0x50, 0x01, 0x01, 0x69, 0x00, 0x00]) + b"referent\x00" + bytes([0x7A])
|
|
ops = [{"mnemonic": "ret", "offset": 0, "raw_bytes": "50", "operands": {}}]
|
|
|
|
metadata = classify_post_ret_metadata(body, ops)
|
|
|
|
self.assertIsNotNone(metadata)
|
|
self.assertEqual(metadata["end_reason"], "debug_symbols_then_end")
|
|
self.assertEqual(metadata["debug_symbol_offset"], 1)
|
|
self.assertEqual(len(metadata["debug_symbols"]), 1)
|
|
self.assertEqual(metadata["debug_symbols"][0]["name"], "referent")
|
|
|
|
def test_render_pseudocode_includes_post_ret_metadata_comment(self) -> None:
|
|
ir = {
|
|
"class": {"class_name": "JELYHACK", "entry_index": 277, "class_id": 0x04D3},
|
|
"event": {"event_name_hint": "use", "slot": 0x01},
|
|
"body": {"end_reason": "debug_symbols_then_end", "decoded_op_count": 1},
|
|
"ops": [{"mnemonic": "ret", "offset": 0, "absolute_body_offset": 0, "raw_bytes": "50", "operands": {}}],
|
|
"debug_symbols": [
|
|
{
|
|
"index": 0,
|
|
"unknown1": 0x01,
|
|
"type_id": 0x69,
|
|
"type_char": "i",
|
|
"bp_offset": 0x00,
|
|
"bp_repr": "[BP+00h]",
|
|
"unknown3": 0x00,
|
|
"name": "referent",
|
|
}
|
|
],
|
|
"field_tags": [],
|
|
}
|
|
|
|
rendered = render_pseudocode(ir)
|
|
|
|
self.assertIn("post-return metadata (not executable)", rendered)
|
|
self.assertIn("debug_symbol referent [BP+00h] type=0x69", rendered)
|
|
|
|
def test_alarmbox_style_forward_flow_renders_without_block_labels(self) -> None:
|
|
blocks = [
|
|
("entry", ["set_info(0x0211, *(arg_06));", "process_exclude();", "if var goto block_0330;"]),
|
|
("block_026D", ["if !Intrinsic0000() goto block_02CB;"]),
|
|
("block_027C", ["if (Item.getFrame(arg_06) != 0) goto block_029B;"]),
|
|
("block_028B", ["goto block_02BA;"]),
|
|
("block_029B", ["if (Item.getFrame(arg_06) != 1) goto block_02BA;"]),
|
|
("block_02AA", ["goto block_02BA;"]),
|
|
("block_02BA", ["spawn class_0A0C_slot_3B(0x00000000);"]),
|
|
("block_02CB", ["a = Item.getStatus(arg_06);", "if ((a & 4) != 0) goto block_032D;"]),
|
|
("block_02E7", ["if (Item.getMapNum(arg_06) != 0) goto block_032D;"]),
|
|
("block_02F9", ["spawn class_0A18_slot_20(pid, 0, *(arg_06), arg_06);", "suspend;"]),
|
|
("block_032D", ["goto block_03C3;"]),
|
|
("block_0330", ["if Intrinsic0000() goto block_03C3;"]),
|
|
("block_033B", ["if (Item.getFrame(arg_06) != 2) goto block_035A;"]),
|
|
("block_034A", ["goto block_0379;"]),
|
|
("block_035A", ["if (Item.getFrame(arg_06) != 3) goto block_0379;"]),
|
|
("block_0369", ["goto block_0379;"]),
|
|
("block_0379", ["spawn class_0A0C_slot_3C(0x00000000);", "if (Item.getMapNum(arg_06) != 0) goto block_03C3;"]),
|
|
("block_039C", ["spawn class_0A18_slot_20(pid, 1, *(arg_06), arg_06);", "suspend;"]),
|
|
("block_03C3", ["return;"]),
|
|
]
|
|
|
|
rendered = render_structured_pseudocode(blocks)
|
|
|
|
self.assertIsNotNone(rendered)
|
|
text = "\n".join(rendered or [])
|
|
self.assertNotIn("block_027C:", text)
|
|
self.assertNotIn("goto block_03C3;", text)
|
|
self.assertIn("if (!var) {", text)
|
|
self.assertIn("if (Intrinsic0000()) {", text)
|
|
self.assertIn("if ((a & 4) == 0) {", text)
|
|
self.assertIn("if (!Intrinsic0000()) {", text)
|
|
|
|
def test_backward_jump_keeps_structured_renderer_disabled(self) -> None:
|
|
blocks = [
|
|
("entry", ["if flag goto block_0010;"]),
|
|
("block_0004", ["return;"]),
|
|
("block_0010", ["goto entry;"]),
|
|
]
|
|
|
|
self.assertIsNone(render_structured_pseudocode(blocks))
|
|
|
|
def test_if_else_branch_renders_as_structured_else(self) -> None:
|
|
blocks = [
|
|
("entry", ["if (Item.getMapNum(arg_06) != 0) goto block_015C;"]),
|
|
("block_00FD", ["if Intrinsic0000() goto block_0132;"]),
|
|
("block_0108", ["spawn class_0A18_slot_20(pid, 0, *(arg_06), arg_06);", "suspend;", "goto block_01C0;"]),
|
|
("block_0132", ["spawn class_0A18_slot_20(pid, 1, *(arg_06), arg_06);", "suspend;", "goto block_01C0;"]),
|
|
("block_015C", ["if Intrinsic0000() goto block_0195;"]),
|
|
("block_0167", ["spawn class_0A18_slot_20(pid, (0 + 0x0080), *(arg_06), arg_06);", "suspend;", "goto block_01C0;"]),
|
|
("block_0195", ["spawn class_0A18_slot_20(pid, (1 + 0x0080), *(arg_06), arg_06);", "suspend;"]),
|
|
("block_01C0", ["return;"]),
|
|
]
|
|
|
|
rendered = render_structured_pseudocode(blocks)
|
|
|
|
self.assertIsNotNone(rendered)
|
|
text = "\n".join(rendered or [])
|
|
self.assertIn("if (Item.getMapNum(arg_06) == 0) {", text)
|
|
self.assertIn("else {", text)
|
|
self.assertNotIn("goto block_01C0;", text)
|
|
|
|
def test_loop_header_and_back_edge_render_as_while(self) -> None:
|
|
blocks = [
|
|
("entry", ["/* loopscr value_u8=0x24 */"]),
|
|
("block_0118", ["if condition goto block_0151;"]),
|
|
("block_011B", ["if (Item.getFrame(item) != 0) goto block_014D;"]),
|
|
("block_012D", ["suspend;"]),
|
|
("block_014D", ["/* loopnext */", "goto block_0118;"]),
|
|
("block_0151", ["return;"]),
|
|
]
|
|
|
|
rendered = render_structured_pseudocode(blocks)
|
|
|
|
self.assertIsNotNone(rendered)
|
|
text = "\n".join(rendered or [])
|
|
self.assertIn("while (!condition) {", text)
|
|
self.assertNotIn("goto block_0118;", text)
|
|
|
|
def test_loop_selector_block_renders_as_for_loop(self) -> None:
|
|
blocks = [
|
|
("entry", ["/* loop_selector item in nearby_items(shape=0x04D0, origin=arg_06) */"]),
|
|
("block_0118", ["if condition goto block_0151;"]),
|
|
("block_011B", ["if (Item.getFrame(item) != 0) goto block_014D;", "suspend;"]),
|
|
("block_014D", ["goto block_0118;"]),
|
|
("block_0151", ["return;"]),
|
|
]
|
|
|
|
rendered = render_structured_pseudocode(blocks)
|
|
|
|
self.assertIsNotNone(rendered)
|
|
text = "\n".join(rendered or [])
|
|
self.assertIn("for item in nearby_items(shape=0x04D0, origin=arg_06) {", text)
|
|
self.assertNotIn("while (!condition) {", text)
|
|
|
|
def test_loop_selector_renders_in_partial_fallback(self) -> None:
|
|
blocks = [
|
|
("entry", ["/* loop_selector item in nearby_items(shape=0x04D0, origin=arg_06) */"]),
|
|
("block_0118", ["if condition goto block_0151;"]),
|
|
("block_011B", ["if other goto block_014D;", "suspend;"]),
|
|
("block_014D", ["goto block_0118;"]),
|
|
("block_0151", ["goto block_0200;"]),
|
|
("block_0200", ["return;"]),
|
|
]
|
|
|
|
rendered = render_partially_structured_blocks(blocks)
|
|
|
|
text = "\n".join(rendered)
|
|
self.assertIn("entry:", text)
|
|
self.assertIn("for item in nearby_items(shape=0x04D0, origin=arg_06) {", text)
|
|
|
|
def test_target_event_reference_prefers_alias_and_class_name(self) -> None:
|
|
target = format_target_event_reference(
|
|
{
|
|
"target_class_id": 0x0A0C,
|
|
"target_class_name_hint": "FREE",
|
|
"target_event_slot": 0x32,
|
|
"target_event_name_hint": None,
|
|
}
|
|
)
|
|
|
|
self.assertEqual(target, "FREE.waitNTimerTicks")
|
|
|
|
def test_selector_0x42_decodes_to_readable_fallback(self) -> None:
|
|
decoded = try_decode_loop_selector(
|
|
[
|
|
{"mnemonic": "loopscr", "operands": {"value_u8": 0x24}},
|
|
{"mnemonic": "push_word_immediate", "operands": {"value_u16": 0x04C8}},
|
|
{"mnemonic": "push_word_immediate", "operands": {"value_u16": 0x01CD}},
|
|
{"mnemonic": "loopscr", "operands": {"value_u8": 0x42}},
|
|
{"mnemonic": "push_byte_immediate", "operands": {"value_u8": 0x32, "value_signed": 50}},
|
|
{"mnemonic": "push_byte_immediate", "operands": {"value_u8": 0x20, "value_signed": 32}},
|
|
{"mnemonic": "mul", "operands": {}},
|
|
{"mnemonic": "push_local_word", "operands": {"bp_offset": 0x0A}},
|
|
{
|
|
"mnemonic": "loop",
|
|
"operands": {"current_var": 0xFE, "string_bytes": 0x6, "loop_type": 0x2},
|
|
},
|
|
],
|
|
0,
|
|
{0xFE: "n", 0x0A: "eventTrigger"},
|
|
)
|
|
|
|
self.assertEqual(
|
|
decoded,
|
|
(
|
|
"n in selector_0x42(arg0=0x04C8, arg1=0x01CD, arg2=(50 * 32), origin=eventTrigger)",
|
|
9,
|
|
),
|
|
)
|
|
|
|
def test_selector_ladder_renders_as_else_if_chain(self) -> None:
|
|
blocks = [
|
|
("entry", ["if (dir != 0) goto block_0358;"]),
|
|
("block_0339", ["x = 0;", "y = -1;", "goto block_0469;"]),
|
|
("block_0358", ["if (dir != 1) goto block_037F;"]),
|
|
("block_0360", ["x = 1;", "y = -1;", "goto block_0469;"]),
|
|
("block_037F", ["if (dir != 2) goto block_03A6;"]),
|
|
("block_0387", ["x = 1;", "y = 0;", "goto block_0469;"]),
|
|
("block_03A6", ["if (dir != 3) goto block_0469;"]),
|
|
("block_03AE", ["x = 1;", "y = 1;", "goto block_0469;"]),
|
|
("block_0469", ["return;"]),
|
|
]
|
|
|
|
rendered = render_structured_pseudocode(blocks)
|
|
|
|
self.assertIsNotNone(rendered)
|
|
text = "\n".join(rendered or [])
|
|
self.assertIn("if (dir == 0) {", text)
|
|
self.assertIn("else if (dir == 1) {", text)
|
|
self.assertIn("else if (dir == 2) {", text)
|
|
self.assertIn("else if (dir == 3) {", text)
|
|
self.assertNotIn("goto block_0469;", text)
|
|
|
|
def test_intrinsic_overlay_prefers_crusader_specific_names(self) -> None:
|
|
regret_intrinsics = get_intrinsic_hints("regret")
|
|
|
|
self.assertEqual(intrinsic_display_name(regret_intrinsics.get(0x0013), 0x0013), "UCMachine.rndRange")
|
|
self.assertEqual(intrinsic_display_name(regret_intrinsics.get(0x0027), 0x0027), "SpriteProcess.createSprite")
|
|
|
|
def test_remorse_intrinsic_overlay_uses_local_table(self) -> None:
|
|
remorse_intrinsics = get_intrinsic_hints("remorse")
|
|
|
|
self.assertEqual(intrinsic_display_name(remorse_intrinsics.get(0x0018), 0x0018), "UCMachine.rndRange")
|
|
self.assertEqual(intrinsic_display_name(remorse_intrinsics.get(0x0015), 0x0015), "AudioProcess.playSFXCru")
|
|
|
|
def test_selector_ladder_renders_in_raw_fallback(self) -> None:
|
|
blocks = [
|
|
("entry", ["goto block_0331;"]),
|
|
("block_0331", ["if (dir != 0) goto block_0358;"]),
|
|
("block_0339", ["x = 0;", "y = -1;", "goto block_0469;"]),
|
|
("block_0358", ["if (dir != 1) goto block_037F;"]),
|
|
("block_0360", ["x = 1;", "y = -1;", "goto block_0469;"]),
|
|
("block_037F", ["if (dir != 2) goto block_0469;"]),
|
|
("block_0387", ["x = 1;", "y = 0;", "goto block_0469;"]),
|
|
("block_0469", ["return;"]),
|
|
]
|
|
|
|
rendered = render_partially_structured_blocks(blocks)
|
|
|
|
text = "\n".join(rendered)
|
|
self.assertIn("block_0331:", text)
|
|
self.assertIn("if (dir == 0) {", text)
|
|
self.assertIn("else if (dir == 1) {", text)
|
|
self.assertIn("else if (dir == 2) {", text)
|
|
self.assertNotIn("block_0358:", text)
|
|
self.assertNotIn("goto block_0469;", text)
|
|
|
|
def test_generic_loop_renders_in_partial_fallback(self) -> None:
|
|
blocks = [
|
|
("entry", ["goto block_01E2;"]),
|
|
("block_01E2", ["counter = 0;"]),
|
|
("block_025C", ["if (counter <= rndNum) goto block_0315;"]),
|
|
("block_0267", ["counter2 = 1;"]),
|
|
("block_026E", ["if (counter2 <= 7) goto block_02B6;"]),
|
|
("block_0276", ["spawn FREE.waitNTimerTicks(pid, 10, 0x00000000);", "suspend;", "counter2 = (1 + counter2);", "goto block_026E;"]),
|
|
("block_02B6", ["counter = (1 + counter);", "goto block_025C;"]),
|
|
("block_0315", ["goto block_01E2;"]),
|
|
]
|
|
|
|
rendered = render_partially_structured_blocks(blocks)
|
|
|
|
text = "\n".join(rendered)
|
|
self.assertIn("while (true) {", text)
|
|
self.assertIn("while (counter > rndNum) {", text)
|
|
self.assertIn("while (counter2 > 7) {", text)
|
|
self.assertNotIn("block_026E:", text)
|
|
self.assertNotIn("goto block_025C;", text)
|
|
|
|
def test_infinite_loop_region_renders_as_while_true(self) -> None:
|
|
blocks = [
|
|
("entry", ["set_info(0x021B, *(arg_06));"]),
|
|
("block_01E2", ["suspend;", "FREE.slot_20(100);", "if (retval > 50) goto block_0318;"]),
|
|
("block_0205", ["FREE.slot_20(pid, 120);", "goto block_046D;"]),
|
|
("block_0318", ["FREE.slot_20(pid, 60);"]),
|
|
("block_046D", ["goto block_01E2;"]),
|
|
("block_0470", ["return;"]),
|
|
]
|
|
|
|
rendered = render_partially_structured_blocks(blocks)
|
|
|
|
text = "\n".join(rendered)
|
|
self.assertIn("while (true) {", text)
|
|
self.assertNotIn("goto block_01E2;", text)
|
|
self.assertNotIn("block_046D:", text)
|
|
|
|
def test_pseudocode_validator_reports_missing_label(self) -> None:
|
|
errors = validate_pseudocode_text(
|
|
"function sample()\n{\n entry:\n goto missing;\n}\n"
|
|
)
|
|
|
|
self.assertEqual(errors, ["line 4: goto target missing has no label"])
|
|
|
|
def test_pseudocode_validator_accepts_balanced_text(self) -> None:
|
|
errors = validate_pseudocode_text(
|
|
"function sample()\n{\n entry:\n while (true) {\n goto entry;\n }\n}\n"
|
|
)
|
|
|
|
self.assertEqual(errors, [])
|
|
|
|
|
|
if __name__ == "__main__":
|
|
unittest.main() |