docs: eval modules without access to pkgs

Replace the `package-options` test with a stricter implementation.

When evaluating modules for use in the docs, provide them with a stubbed
`pkgs` instance that throws an error whenever a package is evaluated.

This ensures we don't accidentally use any packages in defaults or
examples.

Author: MattSturgeon

docs/default.nix

@@ -9,6 +9,56 @@ let
   pkgs = import ./pkgs.nix { inherit system nixpkgs; };
   inherit (pkgs) lib;
 
+  # A stub pkgs instance used while evaluating the nixvim modules for the docs
+  # If any non-meta attr is accessed, the eval will throw
+  noPkgs =
+    let
+      # Known suffixes for package sets
+      suffixes = [
+        "Plugins"
+        "Packages"
+      ];
+
+      # Predicate for whether an attr name looks like a package set
+      # Determines whether stubPackage should recurse
+      isPackageSet = name: builtins.any (lib.flip lib.strings.hasSuffix name) suffixes;
+
+      # Need to retain `meta.homepage` if present
+      stubPackage =
+        prefix: name: package:
+        let
+          loc = prefix ++ [ name ];
+        in
+        if isPackageSet name then
+          lib.mapAttrs (stubPackage loc) package
+        else
+          lib.mapAttrs (_: throwAccessError loc) package
+          // lib.optionalAttrs (package ? meta) { inherit (package) meta; };
+
+      throwAccessError =
+        loc:
+        throw "Attempted to access `${
+          lib.concatStringsSep "." ([ "pkgs" ] ++ loc)
+        }` while rendering the docs.";
+    in
+    lib.fix (
+      self:
+      lib.mapAttrs (stubPackage [ ]) pkgs
+      // {
+        pkgs = self;
+        # The following pkgs attrs are required to eval nixvim, even for the docs:
+        inherit (pkgs)
+          _type
+          stdenv
+          stdenvNoCC
+          symlinkJoin
+          runCommand
+          runCommandLocal
+          writeShellApplication
+          ;
+      }
+    );
+
   nixvimPath = toString ./..;
 
   gitHubDeclaration = user: repo: branch: subpath: {
@@ -37,7 +87,7 @@ let
     modules = [
       {
         isDocs = true;
-        nixpkgs.pkgs = pkgs;
+        _module.args.pkgs = lib.mkForce noPkgs;
       }
     ];
   };

tests/default.nix

@@ -44,7 +44,6 @@ in
   nixpkgs-module = callTest ./nixpkgs-module.nix { };
   plugins-by-name = callTest ./plugins-by-name.nix { };
   generated = callTest ./generated.nix { };
-  package-options = callTest ./package-options.nix { };
   lsp-all-servers = callTest ./lsp-servers.nix { };
 }
 # Expose some tests from the docs as flake-checks too