feat: optionally use WASM function names for compiled methods

[andreas-karlsson]

Summary

Adds a withUseDebugNames(boolean) compiler option that, when enabled, incorporates WASM function names from the module's name section into compiled JVM method names (e.g. foo_0 instead of func_0). This improves readability of stack traces, profiler output, and error messages.

• Off by default — no behavioral change for existing users
• Characters illegal in JVM method names (. ; [ / < >) are sanitized to _ (see JVM Spec §4.2.2)
• The numeric func id is always recoverable from the method name suffix
• extractFuncId replaces the previous startsWith("func_") checks, handling both named and unnamed methods

Usage

  MachineFactoryCompiler.builder(module)
  .withUseDebugNames(true)
      .compile()

Closes #167

Test plan

• Unit tests for methodNameForFunc, sanitizeWasmName, and extractFuncId
• Integration tests verifying named methods are produced when enabled, and not when disabled
• Integration test verifying correct execution with debug names enabled

[andreaTP]

@andreas-karlsson quick note, please make sure you remove AI tools(co-authored) from the final commit as per policy for this repo.

[andreas-karlsson]

@andreaTP I'm happy with the implementation so have promoted the PR for review. I haven't tried it with different compiler toolchains though, and I'm not sure I understand the need? If we see this as a feature to just get better readable output when inspecting stacktraces etc. then I don't think we can do better than replacing every disallowed char with an underscore. The possibility to extract the original func id remains as an escape hatch to retrieve the exact function name.

[andreaTP]

@andreas-karlsson thanks a lot for this PR and for keeping improving the codebase!

I'm not sure I understand the need?

To validate it actually improves readability or produce something that is useful.

I don't think we can do better than replacing every disallowed char with an underscore

This means that, once we get a function name, coming, for example, from Rust we won't be able to re-construct the original name by running rust-demangle on it.

I recall that Rust mangled function names easily become less readable if mangled again.

[andreas-karlsson]

Thanks @andreaTP, always happy to help! And this is something we'd need for our latest developments.

This means that, once we get a function name, coming, for example, from Rust we won't be able to re-construct the original name by running rust-demangle on it.

Indeed, and that is the sticking point. Is this a feature to get best effort (human) readable stacktraces, or is it intended for tooling? I think both are difficult to achieve at once. If we introduce escaping, mangled names will definitely look even more mangled. I think we have the following options:

• Promote readability, but also keep the function index parsable. The way to recover the original name is by parsing the function id and having access to the WASM (or at least the name section). This is what this PR does.
• Promote name fidelity. We need to escape (not santize) disallowed chars. I think the best bet would be URL encoding, as it's a standard and the percent sign is allowed by the JVM. Mangled names will definitely become less readable, but also easily recoverable. I think in this case the cleanest would be if we can avoid encoding the function index. I.e. url decoding the name gives you the original directly.

Or do you see another option? If we want to keep it open we can include a naming strategy option instead to allow both?

[andreas-karlsson]

Here's a concrete proposal for a more generic solution. We add withNamingStrategy and introduce the enum CompilerNamingStrategy with the following values:

• INDEXED This is the default and the fallback if no name exists. Functions are named func_<id>.
• SANITIZED This is what's in this PR. Any disallowed chars are replaced with underscore. We still need to append the function id as names might now collide.
• URL_ENCODED Any disallowed char is simply replaced by percent encoding and no index suffix is added.

So far this only applies to methods but I think later it should also be done for locals and args. The above options should still be compatible. Let me know if you'd prefer a PR in this direction.

[andreaTP]

Thanks for the update @andreas-karlsson !

I think we are going in the right direction, sharing a couple of things that come to mind:

• mangling the second time already mangled strings is going to result in very bad results (experienced it in w9s)
• does the rename impacts backward compatibility? (e.g. is it ok to ship in a minor release?)

What about making the mangling completely configurable user side(e.g. a SPI or similar)? is it a too big of a change? and providing a few default classes already.
This would make it possible, for example, to hook up rustc-demangler when needed and obtain the best possible result.
Wdyt? I'm afraid to increase too much the scope of the PR.