feat(beam): add [<Beam.ModuleName>] to pin a generated module's name

[dbrattli]

Rebased on main now that #4770 has merged.

Why

#4770 derives every Erlang module name from the file's path and qualifies it with its app, which is right for ordinary code. But a module implementing an OTP behaviour, or one called from hand-written Erlang, has its name as part of its contract and needs to be able to say so. That PR listed this as follow-up; this is it.

[<Fable.Core.Beam.ModuleName("my_server")>]
module MyApp.Server

The attribute must be fully qualified — it precedes the module declaration, so it cannot rely on an open. The name has to be a plain unquoted Erlang atom; it must not collide with another module; and it must not be one of OTP's own — pinning is for naming a module its contract requires, not for taking a name OTP already has. All three are compile errors.

How it resolves

This is the one place the naming scheme needs more than a path: an import carries the imported file's path, never its entity. So erlangModuleNameFor maps path → root module (GetRootModule) → entity (TryGetEntity) → attribute. Both already exist on the transforms' Compiler, so no new compiler state is needed — the plumbing I originally feared in #4770 turned out to be unnecessary.

getOutPath takes a module-name resolver, because an .erl file must be named after the module it declares:

• while compiling, the F# AST is right there, so we ask the compiler;
• callers that merely predict an out path (watch's up-to-date check) look the name up in the map of pinned names from the last compilation, kept on State.BeamPinnedModuleNames. Without that memory they would predict the derived name, never find that file on disk, conclude the file had been deleted, and recompile every pinned file on every watch cycle, forever.

An invalid pinned name is reported once, by the file that declares it (checkPinnedModuleName, called from transformFile) — not once per file that imports it.

Two consequences worth flagging

• The duplicate-name check moved to after compilation. A pinned name only exists once the file has been type checked (Project.From starts with an empty implementation-file list), and checking derived names before would reject a clash that a pinned name is there to resolve. Output may be written before the build fails, but it still fails loudly and names both files.
• --run now invokes main:main() instead of deriving the entry module from the predicted output path, which cannot see a pinned name. The scaffold always leaves a main module in src/ — either the entry module itself, or the shim from fix(beam): qualify Erlang module names by their OTP app #4770.

Verification

2562 Beam tests pass, 2 of them new (main is at 2560). The pinned-name test calls the module by the literal atom it is supposed to declare:

let private pinnedValue () : int = emitErlExpr () "fable_tests_pinned:value()"

so a module named anything else is an undef at runtime rather than a silently passing test. The generated file is fable_tests_pinned.erl declaring -module(fable_tests_pinned), confirming both the transform and the CLI honour the attribute.

Also verified on a scratch project pinning my_server:

• the output is my_server.erl, and a watch cycle triggered by an unrelated file recompiles only that file — the pinned module is not dragged in;
• an invalid atom ("MyModule") fails with error FABLE: 'MyModule' is not a valid Erlang module name, reported once against the declaring file even though two other files import it;
• forcing two files onto one pinned name fails the build naming both.

The JS quicktest still passes, since getOutPath is shared by every target.

🤖 Generated with Claude Code