fix tlib formatting

.github/workflows/deploy-website.yml

@@ -12,14 +12,14 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v6
       - name: Setup Pages
-        uses: actions/configure-pages@v5
+        uses: actions/configure-pages@v6
       - name: Install Nix
         uses: DeterminateSystems/nix-installer-action@main
       - name: Update Site
         run: |
           nix run --show-trace ./ci#docs
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@v5
         with:
           path: ./_site
 
@@ -36,6 +36,6 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5
         with:
           token: ${{ secrets.PAT }}

CONTRIBUTING.md

@@ -1,12 +1,12 @@
-# Adding Modules!
+## Adding Modules!
 
 There are 2 kinds of modules in this repository. One kind which defines the `package` option, and one kind which does not.
 
 ### Wrapper Modules
 
 If you are making a wrapper module, i.e. one which **does** define the `config.package` option, and thus wraps a package:
 
-You must define a `wrapperModules/<first_letter>/<your_package_name>/wrapper.nix` file.
+You must define a `wrapperModules/<first_letter>/<your_package_name>/module.nix` file.
 The file must contain a single, unevaluated module. In other words, it must be importable without calling it like a function first.
 
 All wrapper modules must have a `config.meta.maintainers = [ <your wlib.maintainers listing> ];` entry.
@@ -45,31 +45,34 @@ You may optionally set the `meta.description` option to provide a short descript
 
 `pre` will be added after the title and before the content. `post` will be added after the content.
 
+Do not name an option `options` or `config` if there is a chance the module system will try to use them as if they were top level module declarations.
+
 ## Guidelines and Examples:
 
 When you provide an option to `enable` or `disable` something, you should call it `enable` regardless of its default value.
 
 This prevents people from needing to look it up to use it, and prevents contributors from having to think too hard about which to call it.
 
-When you provide a `wlib.types.file` option, you should name it the actual filename, especially if there are multiple, but `configFile` is also OK, especially if it is unambiguous.
+- Placeholders and `config.constructFiles.<name>`
 
-Keep in mind that even if you do not choose to use `wlib.types.file`, the user can usually still override the option that you set to provide the generated path if needed.
+When you generate a file, it is generally better to do so as a string, and create it using the `constructFiles` option.
 
-However, this makes the user of your module search for it, and in some situations, such as when your module is adding stuff to `list` or `DAL` type options, this can be slightly harder to override later.
+This is because, this will make placeholders such as `${placeholder "out"}` work consistently across all your options,
+allowing them to all point to the final wrapper derivation rather than several intermediate ones.
 
-So making use of the `wlib.types.file` type or giving some other method of overriding the filepath when providing a file is generally recommended for this reason.
+What this allows you to do, is manually build files via another option like `constructFiles`, and then refer to that created file within your settings!
 
-- Placeholders
+Making placeholders work in your module makes your modules generally more easily extensible, and is preferred when it is possible to generate a usable string.
 
-When you generate a file, it is generally better to do so as a string, and create it using the `constructFiles` option.
+It works by using `drv.passAsFile` and making a derivation attribute with the file contents, which is copied into place.
 
-This is because, this will make placeholders such as `${placeholder "out"}` work consistently across all your options.
+- `wlib.types.file`
 
-What this allows you to do, is manually build files later using `buildCommand` option or a stdenv phase, and then refer to that created file within your settings!
+When you provide a `wlib.types.file` option, you should name it the actual filename or something suggestive of it, especially if there are multiple, but `configFile` is also OK, especially if it is unambiguous.
 
-Making placeholders work in your module makes your modules generally more easily extensible, and is preferred when it is possible to generate a usable string.
+Keep in mind that even if you do not choose to use `wlib.types.file`, the user can usually still override the option that you set to provide the generated path if needed.
 
-It works by using `drv.passAsFile` and making a derivation attribute with the file contents, which is copied into place.
+So using something like `wlib.types.file` is only truly important when the file you are making an option for is passed to a list-style option, but may still be nice more generally.
 
 Example:
 
@@ -93,11 +96,11 @@ Example:
       '';
     };
     configFile = lib.mkOption {
-      type = wlib.types.file pkgs;
-      default = {
-        path = config.constructFiles.gitconfig.path; # <- we can refer to the placeholder of our constructed file!
-        content = "";
+      type = wlib.types.file {
+        # we can refer to the placeholder of our constructed file!
+        path = lib.mkOptionDefault config.constructFiles.gitconfig.path;
       };
+      default = { };
       description = "Generated git configuration file.";
     };
   };
@@ -118,75 +121,146 @@ Example:
 }
 ```
 
-# Formatting
+## Formatting
 
 `nix fmt`
 
-# Tests
+## Tests
 
 `nix flake check -Lv ./ci`
 
-# Run Site Generator Locally
+## Run Site Generator Locally
 
 `nix run ./ci`
 
 or
 
 `nix run ./ci#docs`
 
-# Writing tests
+To run the tests for an individual wrapper only, run
+
+`nix build ./ci#checks.{system}.wrapperModule-{name}`
+
+Example (neovim on `x86_64-linux`):
+
+`nix build ./ci#checks.x86_64-linux.wrapperModule-neovim`
+
+## Writing Tests
 
 You may also include a `check.nix` file in your module's directory.
 
-It will be provided with the flake `self` value and `pkgs`
+It will be called via `pkgs.callPackage`, provided with the flake `self` value, as well as a test-library `tlib` value.
+(i.e. `pkgs.callPackage your_check.nix { inherit self tlib; }`)
 
-It should build a derivation which tests the wrapper derivation as best you can.
 
-If a command fails, it fails the test. If it builds the derivation successfully, it passes the test.
+We provide a testing library `tlib` that provides an easy-to-use interface to write tests.
 
-If the program gives options for running the program to check the generated configuration is correct, you should do that.
+### Writing Tests for Wrappers
 
-Sometimes it is not easily possible to run the program within a derivation, in those cases, searching the wrapper derivation and other generated files and their contents is also acceptable.
+If you are writing tests for a wrapper module, it is important to pass the name
+of the wrapper to the first argument of the `test` function like in the example 
+below (marked at `(*)`). By doing this, we can grab the specified `wrapper.meta.platforms` config
+of the wrapper (if any) and ensure that the tests are only run on the required platforms.
 
-Example:
 
 ```nix
 {
   pkgs,
   self,
+  tlib,
+  ...
 }:
+
 let
-  gitWrapped = self.wrappers.git.wrap {
-    inherit pkgs;
-    settings = {
-      user = {
-        name = "Test User";
-        email = "test@example.com";
+  inherit (tlib)
+    fileContains
+    isDirectory
+    isFile
+    notIsFile
+    areEqual
+    test
+    ;
+in
+test { wrapper = "direnv"; } { # <-- Specify the name of the wrapper here (*)
+
+  "direnv wrapper should be created" =
+    let
+      wrapper = self.wrappers.direnv.wrap {
+        inherit pkgs;
+        nix-direnv.enable = true;
       };
-    };
+    in
+    [
+      "[[ -d ${wrapper} ]]" # <-- a simple condition to be asserted
+      {                     
+        cond = "[[ -d ${wrapper} ]]";
+        msg = "No directory found for wrapper."; # <-- you can also specify a custom error message
+      }
+      (isDirectory wrapper) # <-- or use pre-defined helpers
+    ];
+
+  "wrapper should output correct version" =
+    let
+      wrapper = self.wrappers.direnv.wrap {
+        inherit pkgs;
+      };
+    in 
+    '' # <-- no need to provide a list if there is only one assertion
+      "${wrapper}/bin/direnv" --version |
+      grep -q "${wrapper.version}"
+    '';
+
+  "math-tests" = { # <-- tests can be arbitrarily grouped
+    addition = [
+      (areEqual 2 (1 + 1))
+      (areEqual 7 (5 + 2))
+    ];
+    multiplication = [
+      (areEqual 1 (1 * 1))
+      (areEqual 10 (5 * 2))
+    ];
   };
-
-in
-pkgs.runCommand "git-test" { } ''
-  "${gitWrapped}/bin/git" config user.name | grep -q "Test User"
-  "${gitWrapped}/bin/git" config user.email | grep -q "test@example.com"
-  touch $out
-''
+}
 ```
 
-If your module declares a list of valid platforms via its `meta.platforms` option, you should disable your test on the relevant platforms like so:
+
+Pre-defined assertions like `isDirectory` or `areEqual` are already available in tlib. 
+Feel free to contribute more if you find new ones that other maintainers might benefit from.
+
+### Writing Tests for Helper Modules or Library Functions
+
+The syntax is identical to [the example above](#writing-tests-for-wrappers), 
+except you don't provide a wrapper but a name:
 
 ```nix
-if builtins.elem pkgs.stdenv.hostPlatform.system self.wrappers.waybar.meta.platforms then
-  pkgs.runCommand "waybar-test" { } ''
-    "${waybarWrapped}/bin/waybar" --version | grep -q "${waybarWrapped.version}"
-    touch $out
-  ''
-else
-  null
+{
+  pkgs,
+  self,
+  tlib,
+  ...
+}:
+
+let
+  inherit (tlib)
+    fileContains
+    isDirectory
+    isFile
+    notIsFile
+    areEqual
+    test
+    ;
+in
+test "my-test" { # <-- Specify an arbitrary name for your test
+# test { name = "my-test" } { # <-- This is equivalent
+
+  "my first test" = [ ... ]; # <-- nothing new here
+  "my second test" = [ ... ];
+}
 ```
 
-# Commit Messages
+If you are writing a helper module, or something very complex, you may wish to have multiple derivations. Simply return a set of them instead.
+
+## Commit Messages
 
 Changes to wrapper modules should be titled `<type>(wrapperModules.<name>): some description`.
 For new additions, the description should be `init`, with any further explanation on subsequent lines
@@ -206,6 +280,6 @@ For everything else, do the best you can to follow conventional commit message s
 
 Why specify this? I was having trouble figuring out what to title my commits. So now I know.
 
-# Questions?
+## Questions?
 
 The [github discussions board](https://github.com/BirdeeHub/nix-wrapper-modules/discussions) is open and a great place to find help!

README.md

@@ -108,14 +108,48 @@ For more information on how to do this, check out the [getting started](https://
 It is the ideal of this project to become a hub for everyone to contribute,
 so that we can all enjoy our portable configurations with as little individual strife as possible.
 
-In service of that ideal, the immediate goal would be to transfer this repo to nix-community the moment that becomes an option.
+In service of that ideal, the plan is that ownership will be transferred to nix-community,
+so that there is community ownership of where our contributions will be maintained.
 
-Eventually I hope to have wrapper modules in nixpkgs, but again, nix-community would be the first step.
+The road-map before beginning that process consists of at least most of the following items:
+
+- Better doc-generation options, less buggy and made more available to individual modules outside of the main repository.
+- Services options for generating service files which can be installed by passing the package to the correct option.
+- Non-intrusive `bubblewrap` helper module, for programs that are difficult to wrap.
+- Better documentation in general. Things should already be covered in the docs, but not yet always in a way digestible for everyone.
+- Maybe 1 or 2 other things.
+
+Once the dust has settled, the process will be started to move it to nix-community,
+and we will start building a core team to maintain the repository long into the future!
 
 ## Short-term Goals
 
 Help us add more modules! Contributors are what makes projects like these which contain modules for so many programs amazing!
 
+## Related Extension Projects:
+
+There may be projects that offer useful additions or pre-configurations of existing modules,
+or new ways of using wrapper modules that do not yet fit in the main repository.
+
+For example, a collection of Neovim modules for various languages would be a good item for this list
+
+- [hm-wrapper-modules](https://github.com/sini/hm-wrapper-modules)
+  - This is a library designed to run home manager modules, figure out what paths it would add,
+    and use `bubblewrap` and a wrapper module to use the home manager module as a wrapper module.
+  - This repository may be useful to create wrapper modules for difficult to wrap programs until more direct ones can be written.
+  - It does not fit in the main repository, because the correct way to do it is to add a `bubblewrap` helper module to the main repository,
+    and figure out what files that program actually needs us to wrap via `bubblewrap` or not.
+
+Hopefully more will be listed here soon!
+
+Some examples why something may not fit in the main repository:
+
+- It doesn't fit in an existing category of offered things.
+
+- It requires more flake inputs beyond `nixpkgs` in order to import it from this repository and use it somewhere.
+
+- It is a never ending job of its own (i.e. making modules for new editor language integrations and plugins for an existing wrapper module like the Neovim one)
+
 ---
 
 ### Why rewrite [lassulus/wrappers](https://github.com/Lassulus/wrappers)?

ci/checks/all-modules-have-maintainers.nix

@@ -1,6 +1,7 @@
 {
   pkgs,
   self,
+  ...
 }:
 
 let

ci/checks/apply.nix

@@ -1,6 +1,7 @@
 {
   pkgs,
   self,
+  ...
 }:
 # TODO: make sure theres no other stuff passing on accident in here
 let

ci/checks/formatting.nix

@@ -1,6 +1,7 @@
 {
   pkgs,
   self,
+  ...
 }:
 
 pkgs.runCommand "formatting-check" { } ''