feat: improve scopedImport with _file attribute and scoped in builtins

also properly override builtins.nixPath in addition to __nixPath.

Author: jbgi

default.nix

@@ -23,16 +23,33 @@ let
           files = leafs path;
         in
         {
-          imports = if scoped == { } then files else map scoped-import files;
+          imports = if scoped == { } then files else map scoped-import-module files;
         };
 
-      scoped-import = builtins.scopedImport (
-        {
-          inherit builtins;
-          __nixPath = [ ];
-        }
-        // scoped
-      );
+      # Like builtins.scopedImport but:
+      # - propagate builtins (but not other free variables) accross nested invocations
+      # - add in scope: `__scoped` and `builtins.scoped` for potential reuse in nested invocations
+      scoped-import =
+        scoped:
+        builtins.scopedImport (
+          {
+            builtins = builtins // {
+              nixPath = [ ];
+              inherit scoped;
+            };
+            __nixPath = [ ];
+            __scoped = scoped;
+          }
+          // scoped
+        );
+
+      scoped-import-module = file: {
+        # Let's not lose track of the original file even if scope-imported:
+        _file = file;
+        imports = [
+          (builtins.scopedImport scoped file)
+        ];
+      };
 
       leafs =
         let

docs/src/content/docs/reference/api.mdx

@@ -169,10 +169,21 @@ The provided attributes are merged into the scope used by `builtins.scopedImport
 Multiple `.addScoped` calls accumulate:
 
 ```nix
-import-tree (it: it.addScoped { foo = 42 }) (it: it.addScoped { bar = 99 })
+import-tree (it: it.addScoped { foo = 42 }) (it: it.addScoped { bar = 99 }) ./modules
 # modules can access both foo and bar
 ```
 
+Scoped variables can be accessed inside scoped-imported modules as `builtins.scoped`:
+
+```nix
+# module.nix
+{ 
+  imports = [ (import-tree.addScoped (builtins.scoped // { bar = foo; }) ./other-modules) ];
+  # other-modules can now access `bar` directly in addition to `foo` and `mylib`
+}
+
+```
+
 ---
 
 ## Output