refactor(readTree): Move 'restrictFolder' function into readTree

This is generally useful for readTree users and should be part of
readTree itself.

This is a move towards exposing several readTree-related features from
the library itself, in the future also including logic like 'gather'.

Note that this has a small functional change: In error messages of the
function, the notation for accessing Nix attributes is now used rather
than the Perforce-style `//` notation common in TVL.

For example, an error at `//web/tvl/logo` will produce `web.tvl.logo`
in the error message (which corresponds to the readTree attribute
itself).

This makes more sense for non-TVL consumers of readTree, as the
Perforce-style notation is custom to us specifically.

Change-Id: I8e199e473843c40db40b404c20d2c71f48a0f658

nix/readTree/default.nix

@@ -20,13 +20,13 @@
 let
   inherit (builtins)
     attrNames
-    baseNameOf
     concatStringsSep
+    elem
+    elemAt
     filter
     hasAttr
     head
     isAttrs
-    length
     listToAttrs
     map
     match
@@ -138,4 +138,35 @@ in {
         rootDir = true;
         parts = [];
       };
+
+  # In addition to readTree itself, some functionality is exposed that
+  # is useful for users of readTree.
+
+  # Create a readTree filter disallowing access to the specified
+  # top-level folder in the repository, except for specific exceptions
+  # specified by their (full) paths.
+  #
+  # Called with the arguments:
+  #
+  #   folder: Name of the restricted top-level folder (e.g. 'experimental')
+  #
+  #   exceptions: List of readTree parts (e.g. [ [ "services" "some-app" ] ]),
+  #               which should be able to access the restricted folder.
+  #
+  #   reason: Textual explanation for the restriction (included in errors)
+  restrictFolder = { folder, exceptions ? [], reason }: parts: args:
+    if (elemAt parts 0) == folder || elem parts exceptions
+    then args
+    else args // {
+      depot = args.depot // {
+        "${folder}" = throw ''
+          Access to targets under //${folder} is not permitted from
+          other repository paths. Specific exceptions are configured
+          at the top-level.
+
+          ${reason}
+          At location: ${builtins.concatStringsSep "." parts}
+        '';
+      };
+    };
 }