Optionally request "publisher" in modules

Closes #23

docs/folder-structure.md

@@ -184,6 +184,12 @@ For the following folder names, we also map them to the following outputs:
 
 These and other unrecognized types also make to `modules.<type>.<name>`.
 
+Each module can optionally be wrapped in a function that takes a single named
+argument called `publisher`. If used, that function will be called with `publisher`
+set to the current, defining flake before exposing that module.
+This can be used to reference the defining flake when the module
+is imported in another flake and the module argument `flake` points the consumer.
+
 ### `package.nix`, `formatter.nix`, `packages/<pname>(.nix|/default.nix)`
 
 This `packages/` folder contains all your packages.

lib/default.nix

@@ -204,6 +204,23 @@ let
         ) (lib.attrsToList hosts)
       );
 
+      # Check if the given module is wrapped in a function expecting "publisher" as a named argument,
+      # and - if so - call that function with the current flake. This enables us to reference
+      # the publishing flake when re-using exported modules in consuming, downstream flakes.
+      withPublisher =
+        module:
+        let
+          module' = if builtins.isString module || builtins.isPath module then import module else module;
+          wantsPublisher =
+            builtins.isFunction module' && builtins.hasAttr "publisher" (builtins.functionArgs module');
+        in
+        if wantsPublisher then
+          lib.modules.importApply module {
+            publisher = flake;
+          }
+        else
+          module;
+
       modules =
         let
           path = src + "/modules";
@@ -212,7 +229,9 @@ let
           );
         in
         lib.optionalAttrs (builtins.pathExists path) (
-          lib.genAttrs moduleDirs (name: importDir (path + "/${name}") entriesPath)
+          lib.genAttrs moduleDirs (
+            name: lib.mapAttrs (name: module: withPublisher module) (importDir (path + "/${name}") entriesPath)
+          )
         );
     in
     # FIXME: maybe there are two layers to this. The blueprint, and then the mapping to flake outputs.