feature: shadow alias module

CHANGES.md

@@ -1,6 +1,8 @@
 3.5.0 (unreleased)
 ------------------
 
+- Shadow alias module `Foo__` when building a library `Foo` (#6126, @rgrinberg)
+
 - Allow dune describe workspace to accept directories as arguments.
   The provided directories restrict the worskpace description to those
   directories. (#6107, fixes #3893, @esope)

src/dune_rules/module_compilation.ml

@@ -283,9 +283,10 @@ module Alias_module = struct
   type t =
     { main_module : Module_name.t
     ; aliases : alias list
+    ; shadowed : Module_name.t list
     }
 
-  let to_ml { main_module; aliases } =
+  let to_ml { main_module; aliases; shadowed } =
     let b = Buffer.create 16 in
     Buffer.add_string b "(* generated by dune *)\n";
     let main_module = Module_name.to_string main_module in
@@ -295,22 +296,38 @@ module Alias_module = struct
           main_module local_name local_name
           (Module_name.Unique.to_name ~loc:Loc.none obj_name
           |> Module_name.to_string));
+    List.iter shadowed ~f:(fun shadowed ->
+        Printf.bprintf b
+          "\n\
+           module %s = struct end\n\
+           [@@deprecated \"this module is shadowed\"]\n"
+          (Module_name.to_string shadowed));
     Buffer.contents b
 
-  let of_modules modules =
+  let of_modules project modules =
     let main_module = Modules.main_module_name modules |> Option.value_exn in
     let aliases =
       Modules.for_alias modules
       |> Module_name.Map.to_list_map ~f:(fun local_name m ->
              let obj_name = Module.obj_name m in
              { local_name; obj_name })
     in
-    { main_module; aliases }
+    let shadowed =
+      if Dune_project.dune_version project < (3, 5) then []
+      else
+        match Modules.alias_module modules with
+        | None -> []
+        | Some alias_module -> [ Module.name alias_module ]
+    in
+    { main_module; aliases; shadowed }
 end
 
 let build_alias_module cctx alias_module =
   let modules = Compilation_context.modules cctx in
-  let alias_file () = Alias_module.of_modules modules |> Alias_module.to_ml in
+  let alias_file () =
+    let project = Compilation_context.scope cctx |> Scope.project in
+    Alias_module.of_modules project modules |> Alias_module.to_ml
+  in
   let cctx = Compilation_context.for_alias_module cctx alias_module in
   let sctx = Compilation_context.super_context cctx in
   let file = Option.value_exn (Module.file alias_module ~ml_kind:Impl) in

test/blackbox-tests/test-cases/alias-module.t

@@ -1,7 +1,7 @@
 Test alias module for wrapped libraries:
 
   $ cat >dune-project <<EOF
-  > (lang dune 3.4)
+  > (lang dune 3.5)
   > EOF
 
   $ cat >dune <<EOF
@@ -16,3 +16,6 @@ Test alias module for wrapped libraries:
 
   (** @canonical Foo.Bar *)
   module Bar = Foo__Bar
+
+  module Foo__ = struct end
+  [@@deprecated "this module is shadowed"]