From 35bf15c510cb50ee8152d911c686e5eccdb95c15 Mon Sep 17 00:00:00 2001
From: johnohhh1 <147962948+johnohhh1@users.noreply.github.com>
Date: Wed, 14 Oct 2026 20:11:11 -0400
Subject: [PATCH] fix(tools): recognize guest module identities in import audit

Resolve module dependencies through ELF SONAMEs and declared SCE module identities, preserving exact-name precedence and rejecting ambiguity. Keep each module import counted once across aliases and repeated inputs.

Middle Ages Ping Pong (PPSA28319) reaches a rendered match on current main, but its Il2CppUserAssemblies.prx declares Il2cppUserAssemblies. The audit falsely reported four missing imports and a missing module. Add section-based and sectionless regression coverage and document the matching rules.
---
 docs/user/USAGE.md               |   2 +
 tools/import_audit.py            |  65 +++++++++---
 tools/tests/test_import_audit.py | 163 ++++++++++++++++++++++++++++++-
 3 files changed, 213 insertions(+), 17 deletions(-)

diff --git a/docs/user/USAGE.md b/docs/user/USAGE.md
index 8953f29bb746..8dfbd41f5bab 100644
--- a/docs/user/USAGE.md
+++ b/docs/user/USAGE.md
@@ -382,6 +382,8 @@ Module registries mark ELF weak imports with `"weak": true`, allowing the audit'
 
 ELF modules in `--modules` are audited regardless of filename: their undefined symbols are classified against the built libraries and the other modules' exports, with the module file named in the report, and the libraries they need must have a file in `--libs` or `--modules`. Ordinary non-module sidecars are ignored; malformed ELF, PE/SELF containers and non-ELF files with module extensions remain errors. The audit reads dynamic tables from ELF section headers or, for sectionless files, from `PT_DYNAMIC` and a SysV or GNU hash table.
 
+Module dependencies also resolve through their declared ELF SONAME or SCE module identity. Exact filenames and SONAMEs take precedence over identities; ambiguous names fail the audit. Each module's imports are counted once even when several names refer to it.
+
 Each registry has a companion with the same prefix and the suffix `.needed.json`, listing its host library dependencies, including declared `DT_NEEDED` entries with no imports. Dependencies supplied by converted bundled modules, including their aliases, are omitted. The executable's companion includes host dependencies of its bundled modules. The audit reads these companions automatically; keep them beside the registries. Older registries without companions still work, but cannot report dependencies that have no imports; regenerate them with `--registry` to include those dependencies.
 
 The report also lists needed libraries that have no file in `--libs` or `--modules`, including dependencies with zero imports. These do not increase the import or reference counts. Windows can skip a missing dependency when no import needs it; Linux still needs the file. The audit also lists imports exported only by a library other than the one they name; those resolve on Linux and can fail on Windows.
diff --git a/tools/import_audit.py b/tools/import_audit.py
index be6cdf0efcdf..d45531861427 100644
--- a/tools/import_audit.py
+++ b/tools/import_audit.py
@@ -14,6 +14,7 @@
 ROOT = Path(__file__).resolve().parent.parent
 PRX = ROOT / "core" / "libs" / "prx"
 MODULE_SUFFIX = "#"
+MODULE_EXTENSIONS = (".prx", ".sprx", ".suprx", ".debug_prx")
 CLASSES = ("implemented", "stub", "absent", "module")
 PE_DIRECTORY_OFFSET = {0x20b: 112, 0x10b: 96}
 
@@ -57,7 +58,18 @@ def elf_sections(path, data):
     return [unpack("<IIQQQQIIQQ", data, section_offset + index * 64, path, f"section header {index}") for index in range(section_count)]
 
 
-def elf_program_dynamic_symbols(path, data):
+def add_module_name(path, data, offset, size, tag, value, names):
+    if names is None or tag not in (14, 0x6100000d, 0x61000043):
+        return
+    position = value if tag == 14 else value & 0xffffffff
+    name = cstring(data, offset + position, offset + size, path, "module name")
+    forbidden = "\\:$\r\n" if tag == 14 else "/\\:$\r\n"
+    if not name or any(character in name for character in forbidden):
+        raise AuditError(f"{path}: invalid module name {name!r}")
+    names["sonames" if tag == 14 else "identities"].add(name)
+
+
+def elf_program_dynamic_symbols(path, data, module_names=None):
     header = unpack("<16sHHIQQQIHHHHHH", data, 0, path, "ELF header")
     ident, program_offset, program_size, program_count = header[0], header[5], header[9], header[10]
     if ident[6] != 1 or header[3] != 1:
@@ -85,6 +97,7 @@ def file_offset(address, size, what):
         raise AuditError(f"{path}: dynamic segment size {dynamic_size} is not a multiple of 16")
     dynamic = {}
     needed_offsets = []
+    named_entries = []
     for position in range(0, dynamic_size, 16):
         tag, value = unpack("<qQ", data, dynamic_offset + position, path, "dynamic entry")
         if tag == 0:
@@ -93,6 +106,8 @@ def file_offset(address, size, what):
             needed_offsets.append(value)
         else:
             dynamic[tag] = value
+        if tag in (14, 0x6100000d, 0x61000043):
+            named_entries.append((tag, value))
     string_address = dynamic.get(5)
     string_size = dynamic.get(10)
     symbol_address = dynamic.get(6)
@@ -100,6 +115,8 @@ def file_offset(address, size, what):
     if None in (string_address, string_size, symbol_address, symbol_size) or symbol_size != 24 or string_size == 0:
         raise AuditError(f"{path}: incomplete dynamic string or symbol table")
     string_offset = file_offset(string_address, string_size, "dynamic string table")
+    for tag, value in named_entries:
+        add_module_name(path, data, string_offset, string_size, tag, value, module_names)
 
     symbol_count = None
     if 4 in dynamic:
@@ -183,10 +200,10 @@ def elf_exports(path, data):
     return names
 
 
-def elf_imports(path, data):
+def elf_imports(path, data, module_names=None):
     header = unpack("<16sHHIQQQIHHHHHH", data, 0, path, "ELF header")
     if not header[6] or header[6] >= len(data):
-        imports, _, needed = elf_program_dynamic_symbols(path, data)
+        imports, _, needed = elf_program_dynamic_symbols(path, data, module_names)
         return imports, needed
     sections = elf_sections(path, data)
     symbols = set()
@@ -214,6 +231,7 @@ def elf_imports(path, data):
                     break
                 if tag == 1:
                     needed.add(cstring(data, strings_offset + value, strings_offset + strings_size, path, "needed library name"))
+                add_module_name(path, data, strings_offset, strings_size, tag, value, module_names)
     return symbols, needed
 
 
@@ -429,10 +447,12 @@ def module_files(directory):
             raise AuditError(f"{file}: expected ELF module (first bytes {magic!r})")
 
 
-def read_modules(directories):
+def read_modules(directories, needed_names=()):
     imports = {}
     exports = defaultdict(set)
     images = {}
+    aliases = {}
+    identities = defaultdict(set)
     for directory in directories:
         for file in module_files(directory):
             data = file.read_bytes()
@@ -443,16 +463,34 @@ def read_modules(directories):
                     raise AuditError(f"ambiguous guest module {file.name}: {previous} and {file} have different contents")
                 continue
             images[file.name] = (file, digest)
+            names = {"sonames": set(), "identities": set()}
             if data.startswith(b"MZ"):
                 imports[file.name] = ([], [])
-                names = pe_exports(file, data)
+                exported = pe_exports(file, data)
             else:
-                symbols, needed = elf_imports(file, data)
+                symbols, needed = elf_imports(file, data, names)
                 imports[file.name] = (sorted(symbols), sorted(needed))
-                names = elf_exports(file, data)
-            for name in names:
+                exported = elf_exports(file, data)
+            for name in {file.name} | names["sonames"]:
+                if name in aliases and aliases[name] != file:
+                    raise AuditError(f"ambiguous guest module name {name}: {aliases[name]} and {file}")
+                aliases[name] = file
+            for name in names["identities"]:
+                identities[name].add(file)
+            for name in exported:
                 exports[name.split(MODULE_SUFFIX, 1)[0]].add(file.name)
-    return imports, {name: sorted(files) for name, files in exports.items()}
+    requested = set(needed_names) | {name for _, needed in imports.values() for name in needed}
+    for name in sorted(requested):
+        if name in aliases:
+            continue
+        suffix = next((extension for extension in MODULE_EXTENSIONS if name.endswith(extension)), "")
+        stem = name[:-len(suffix)] if suffix else name
+        providers = identities.get(name, set()) | identities.get(stem, set())
+        if len(providers) > 1:
+            raise AuditError(f"ambiguous guest module identity {name}: " + ", ".join(str(file) for file in sorted(providers)))
+        if providers:
+            aliases[name] = next(iter(providers))
+    return imports, {name: sorted(files) for name, files in exports.items()}, set(aliases)
 
 
 def nids_of(name, aliases):
@@ -751,12 +789,13 @@ def main(argv=None):
         needed = sorted({library for path in dependency_registries for library in read_needed_registry(path)})
         exports, libraries = built_libraries(args.libs)
         host_dependencies, windows = built_host_dependencies(args.libs)
-        module_imports, module_exports = read_modules(args.modules)
-        modules = set(module_imports)
-        modules |= {name.removesuffix(".guest.prx") for name in modules if name.endswith(".guest.prx")}
+        module_imports, module_exports, modules = read_modules(args.modules, set(needed) | {library for _, library, _ in imports if library})
+        host_modules = set(module_imports)
+        host_modules |= {name.removesuffix(".guest.prx") for name in host_modules if name.endswith(".guest.prx")}
+        modules |= host_modules
         modules = ModuleNames(modules, fold=bool(windows))
         records, missing = audit(imports, exports, source_stubs(args.source), libraries, modules, module_imports, module_exports, needed_libraries=needed)
-        missing_hosts = audit_host_dependencies(host_dependencies, libraries, modules, windows)
+        missing_hosts = audit_host_dependencies(host_dependencies, libraries, host_modules, windows)
         if args.names:
             attach_names(records, load_names(args.names))
         summary = summarize(records, sum(record["references"] for record in records), missing, missing_hosts)
diff --git a/tools/tests/test_import_audit.py b/tools/tests/test_import_audit.py
index adf98d674225..c64c6e761626 100644
--- a/tools/tests/test_import_audit.py
+++ b/tools/tests/test_import_audit.py
@@ -23,7 +23,7 @@
 MESSAGE_NAME = "sceMsgDialogProgressBarSetValue"
 
 
-def build_elf(symbols, needed=()):
+def build_elf(symbols, needed=(), module_names=()):
     strings = b"\0"
     entries = [struct.pack("<IBBHQQ", 0, 0, 0, 0, 0, 0)]
     for name, index, info in symbols:
@@ -33,12 +33,16 @@ def build_elf(symbols, needed=()):
     for library in needed:
         libraries.append(len(strings))
         strings += library.encode() + b"\0"
+    names = []
+    for tag, name in module_names:
+        names.append((tag, len(strings) | (0x10100000000 if tag != 14 else 0)))
+        strings += name.encode() + b"\0"
     table = b"".join(entries)
     table_offset = 64 + len(strings)
     table_offset += -table_offset % 8
     dynamic_offset = table_offset + len(table)
     dynamic_offset += -dynamic_offset % 8
-    pairs = [(1, offset) for offset in libraries]
+    pairs = [(1, offset) for offset in libraries] + names
     if pairs:
         pairs.append((0, 0))
     dynamic = b"".join(struct.pack("<qQ", tag, value) for tag, value in pairs)
@@ -56,7 +60,7 @@ def build_elf(symbols, needed=()):
     return bytes(image)
 
 
-def build_sectionless_elf(symbols, needed=(), gnu_hash=False):
+def build_sectionless_elf(symbols, needed=(), gnu_hash=False, module_names=()):
     strings = b"\0"
     entries = [struct.pack("<IBBHQQ", 0, 0, 0, 0, 0, 0)]
     for name, index, info in symbols:
@@ -66,6 +70,10 @@ def build_sectionless_elf(symbols, needed=(), gnu_hash=False):
     for library in needed:
         libraries.append(len(strings))
         strings += library.encode() + b"\0"
+    names = []
+    for tag, name in module_names:
+        names.append((tag, len(strings) | (0x10100000000 if tag != 14 else 0)))
+        strings += name.encode() + b"\0"
     program_offset = 64
     content_offset = program_offset + 2 * 56
     strings_offset = content_offset
@@ -81,6 +89,7 @@ def build_sectionless_elf(symbols, needed=(), gnu_hash=False):
         hash_tag = 4
     dynamic_offset = (hash_offset + len(hash_table) + 7) & ~7
     dynamic = b"".join(struct.pack("<qQ", 1, value) for value in libraries)
+    dynamic += b"".join(struct.pack("<qQ", tag, value) for tag, value in names)
     dynamic += b"".join(struct.pack("<qQ", tag, value) for tag, value in (
         (5, 0x400000 + strings_offset),
         (10, len(strings)),
@@ -682,6 +691,151 @@ def test_module_needed_library_without_a_file_is_missing(self):
         self.assertEqual(data["missing_libraries"], {"libSceMissing.prx": 1})
         self.assertIn("libSceMissing.prx", out)
 
+    def test_declared_module_names_resolve_imports_and_dependencies(self):
+        work = self.work
+        (work.libs / "libc.prx").write_bytes(exporting("CCCCCCCCCCC"))
+        registry, result = work.root / "game.registry.json", work.root / "audit.json"
+        for format in ("sections", "sysv", "gnu", "out_of_file_sysv", "out_of_file_gnu"):
+            for tag in (14, 0x6100000d, 0x61000043):
+                suffixes = ("",) if tag == 14 else ("", ".prx", ".sprx", ".suprx", ".debug_prx")
+                for suffix in suffixes:
+                    with self.subTest(format=format, tag=hex(tag), suffix=suffix):
+                        alias = "Declared.prx" if tag == 14 else "Declared" + suffix
+                        name = "Declared.prx" if tag == 14 else "Declared"
+                        provider = [("AAAAAAAAAAA", 1, GLOBAL_FUNCTION), ("CCCCCCCCCCC", 0, GLOBAL_FUNCTION)]
+                        consumer = [("AAAAAAAAAAA", 0, GLOBAL_FUNCTION)]
+                        if format == "sections":
+                            image = build_elf(provider, module_names=[(tag, name)])
+                            dependency = build_elf(consumer, [alias])
+                        else:
+                            image = build_sectionless_elf(provider, gnu_hash=format.endswith("gnu"), module_names=[(tag, name)])
+                            dependency = build_sectionless_elf(consumer, [alias], gnu_hash=format.endswith("gnu"))
+                            if format.startswith("out_of_file"):
+                                image, dependency = bytearray(image), bytearray(dependency)
+                                for module in (image, dependency):
+                                    struct.pack_into("<Q", module, 40, len(module) + 64)
+                                    struct.pack_into("<H", module, 60, 38)
+                        (work.modules / "Different.prx").write_bytes(image)
+                        (work.modules / "consumer.prx").write_bytes(dependency)
+                        write_registry(registry, [("AAAAAAAAAAA", alias), ("AAAAAAAAAAA", "Different.prx")])
+                        (work.root / "game.needed.json").write_text(json.dumps([alias]))
+                        code, _, err = work.run(registry, "--json", str(result))
+                        self.assertEqual((code, err), (0, ""))
+                        data = json.loads(result.read_text())
+                        self.assertEqual(data["missing_libraries"], {})
+                        self.assertEqual(data["references"], 4)
+                        self.assertEqual(data["unique_by_class"], {"implemented": 2, "stub": 0, "absent": 0, "module": 2})
+                        self.assertIsNone(data["stops"][0]["nid"])
+
+    def test_host_dependencies_require_filenames_not_module_identities(self):
+        work = self.work
+        registry, result = work.root / "game.json", work.root / "audit.json"
+        write_registry(registry, [("AAAAAAAAAAA", "Declared.prx")])
+        for format in ("elf", "pe"):
+            for tag in (14, 0x6100000d, 0x61000043):
+                with self.subTest(format=format, tag=hex(tag)):
+                    host = (build_elf([], ["Declared.prx"]) if format == "elf"
+                            else build_pe_with_imports(["Declared.prx"], []))
+                    (work.libs / "host.prx").write_bytes(host)
+                    name = "Declared.prx" if tag == 14 else "Declared"
+                    (work.modules / "Different.prx").write_bytes(build_elf(
+                        [("AAAAAAAAAAA", 1, GLOBAL_FUNCTION)], module_names=[(tag, name)]))
+                    code, _, err = work.run(registry, "--json", str(result))
+                    self.assertEqual((code, err), (1, ""))
+                    data = json.loads(result.read_text())
+                    self.assertEqual(data["missing_libraries"], {})
+                    self.assertEqual(data["unique_by_class"]["absent"], 0)
+                    self.assertEqual(data["unique_by_class"]["module"], 1)
+                    self.assertEqual(data["missing_host_dependencies"], [
+                        {"importer": "host.prx", "chain": ["host.prx", "Declared.prx"]}])
+                    exact = work.modules / "Declared.prx"
+                    (work.modules / "Different.prx").rename(exact)
+                    code, _, err = work.run(registry, "--json", str(result))
+                    self.assertEqual((code, err), (0, ""))
+                    data = json.loads(result.read_text())
+                    self.assertEqual(data["missing_host_dependencies"], [])
+                    self.assertEqual(data["missing_libraries"], {})
+                    exact.unlink()
+
+    def test_module_identity_does_not_fold_undeclared_filename_case(self):
+        work = self.work
+        (work.libs / "libc.prx").write_bytes(exporting())
+        (work.modules / "Provider.prx").write_bytes(exporting("AAAAAAAAAAA"))
+        registry, result = work.root / "game.json", work.root / "audit.json"
+        write_registry(registry, [("AAAAAAAAAAA", "provider.prx")])
+        code, _, err = work.run(registry, "--json", str(result))
+        self.assertEqual((code, err), (1, ""))
+        data = json.loads(result.read_text())
+        self.assertEqual(data["missing_libraries"], {"provider.prx": 1})
+        self.assertEqual(data["imports"][0]["class"], "absent")
+
+    def test_ambiguous_module_names_preserve_report(self):
+        work = self.work
+        (work.libs / "libc.prx").write_bytes(exporting())
+        registry, result = work.root / "game.json", work.root / "audit.json"
+        previous = b'{"previous":"complete report"}\n'
+        for tag in (14, 0x6100000d, 0x61000043):
+            with self.subTest(tag=hex(tag)):
+                name = "Declared.prx" if tag == 14 else "Declared"
+                for file in ("first.prx", "second.prx"):
+                    (work.modules / file).write_bytes(build_elf([], module_names=[(tag, name)]))
+                write_registry(registry, [("AAAAAAAAAAA", "Declared.prx")])
+                result.write_bytes(previous)
+                code, out, err = work.run(registry, "--json", str(result))
+                self.assertEqual((code, out), (2, ""))
+                self.assertIn("ambiguous guest module", err)
+                self.assertEqual(result.read_bytes(), previous)
+
+    def test_exact_module_filename_precedes_other_module_identities(self):
+        work = self.work
+        (work.libs / "libc.prx").write_bytes(exporting())
+        (work.modules / "Declared.prx").write_bytes(exporting())
+        for file in ("first.prx", "second.prx"):
+            (work.modules / file).write_bytes(build_elf([], module_names=[(0x61000043, "Declared")]))
+        registry = work.root / "game.json"
+        write_registry(registry, [("AAAAAAAAAAA", "Declared.prx")])
+        code, _, err = work.run(registry)
+        self.assertEqual((code, err), (0, ""))
+
+    def test_multiple_module_names_and_identical_files_do_not_repeat_imports(self):
+        work = self.work
+        (work.libs / "libc.prx").write_bytes(exporting("CCCCCCCCCCC"))
+        other = work.root / "other-modules"
+        other.mkdir()
+        image = build_elf([("CCCCCCCCCCC", 0, GLOBAL_FUNCTION)], module_names=[
+            (14, "Declared.prx"), (0x6100000d, "Original"), (0x61000043, "Alternate")])
+        for directory in (work.modules, other):
+            (directory / "provider.prx").write_bytes(image)
+        registry, result = work.root / "game.json", work.root / "audit.json"
+        write_registry(registry, [("AAAAAAAAAAA", name) for name in ("Declared.prx", "Original.prx", "Alternate.sprx")])
+        code, _, err = work.run(registry, "--modules", str(other), "--strict-providers", "--json", str(result))
+        self.assertEqual((code, err), (0, ""))
+        data = json.loads(result.read_text())
+        self.assertEqual(data["references"], 4)
+        self.assertEqual(data["unique_by_class"], {"implemented": 1, "stub": 0, "absent": 0, "module": 3})
+
+    def test_invalid_declared_module_name_preserves_report(self):
+        work = self.work
+        (work.libs / "libc.prx").write_bytes(exporting())
+        registry, result = work.root / "game.json", work.root / "audit.json"
+        write_registry(registry, [])
+        previous = b'{"previous":"complete report"}\n'
+        for format in ("sections", "sysv", "gnu"):
+            for tag in (14, 0x6100000d, 0x61000043):
+                for name in ("", "bad\\name"):
+                    with self.subTest(format=format, tag=hex(tag), name=name):
+                        symbols = [("AAAAAAAAAAA", 1, GLOBAL_FUNCTION)]
+                        if format == "sections":
+                            image = build_elf(symbols, module_names=[(tag, name)])
+                        else:
+                            image = build_sectionless_elf(symbols, gnu_hash=format == "gnu", module_names=[(tag, name)])
+                        (work.modules / "provider.prx").write_bytes(image)
+                        result.write_bytes(previous)
+                        code, out, err = work.run(registry, "--json", str(result))
+                        self.assertEqual((code, out), (2, ""))
+                        self.assertIn("invalid module name", err)
+                        self.assertEqual(result.read_bytes(), previous)
+
     def test_conflicting_module_files_preserve_or_leave_no_json_report(self):
         work = self.work
         first, second = work.modules, work.root / "other-modules"
@@ -1427,8 +1581,9 @@ def test_read_modules_uses_pe_exports_and_no_host_imports(self):
         module = self.work.modules / "libc.prx.guest.prx"
         module.write_bytes(build_pe(["sceKernelGettimeofday#guest", "sceKernelSleep"]))
 
-        imports, exports = import_audit.read_modules([self.work.modules])
+        imports, exports, modules = import_audit.read_modules([self.work.modules])
 
+        self.assertEqual(modules, {module.name})
         self.assertEqual(imports, {module.name: ([], [])})
         self.assertEqual(exports, {
             "sceKernelGettimeofday": [module.name],