chore(lib/treewide): cleanup directory struture of lib. See lib/readme.md for details

2025-04-02 10:32:58 +02:00
parent e5d8245751
commit 6e16d1345e
21 changed files with 92 additions and 94 deletions
--- a/lib/inventory/frontmatter/default.nix
+++ b/lib/inventory/frontmatter/default.nix
@@ -0,0 +1,111 @@
+{ lib, clanLib }:
+let
+  # Trim the .nix extension from a filename
+  trimExtension = name: builtins.substring 0 (builtins.stringLength name - 4) name;
+
+  jsonWithoutHeader = clanLib.jsonschema {
+    includeDefaults = true;
+    header = { };
+  };
+
+  getModulesSchema =
+    modules:
+    lib.mapAttrs (
+      _moduleName: rolesOptions:
+      lib.mapAttrs (_roleName: options: jsonWithoutHeader.parseOptions options { }) rolesOptions
+    ) (clanLib.evalClan.evalClanModulesWithRoles modules);
+
+  evalFrontmatter =
+    {
+      moduleName,
+      instanceName,
+      resolvedRoles,
+      allModules,
+    }:
+    lib.evalModules {
+      specialArgs = {
+        inherit moduleName resolvedRoles instanceName;
+        allRoles = getRoles allModules moduleName;
+      };
+      modules = [
+        (getFrontmatter allModules.${moduleName} moduleName)
+        ./interface.nix
+      ];
+    };
+
+  # For Documentation purposes only
+  frontmatterOptions =
+    (lib.evalModules {
+      specialArgs = {
+        moduleName = "{moduleName}";
+        allRoles = [ "{roleName}" ];
+      };
+      modules = [
+        ./interface.nix
+      ];
+    }).options;
+
+  getRoles =
+    allModules: serviceName:
+    lib.mapAttrsToList (name: _value: trimExtension name) (
+      lib.filterAttrs (name: type: type == "regular" && lib.hasSuffix ".nix" name) (
+        builtins.readDir (
+          if allModules ? ${serviceName} then
+            allModules.${serviceName} + "/roles"
+          else
+            throw "ClanModule not found: '${serviceName}'. Make sure the module is added in the 'clanModules' attribute of clan-core."
+        )
+      )
+    );
+
+  checkConstraints = args: (evalFrontmatter args).config.constraints.assertions;
+
+  getReadme =
+    modulepath: modulename:
+    let
+      readme = modulepath + "/README.md";
+      readmeContents =
+        if (builtins.pathExists readme) then
+          (builtins.readFile readme)
+        else
+          throw "No README.md found for module ${modulename} (expected at ${readme})";
+    in
+    readmeContents;
+
+  getFrontmatter =
+    modulepath: modulename:
+    let
+      content = getReadme modulepath modulename;
+      parts = lib.splitString "---" content;
+      # Partition the parts into the first part (the readme content) and the rest (the metadata)
+      parsed = builtins.partition ({ index, ... }: if index >= 2 then false else true) (
+        lib.filter ({ index, ... }: index != 0) (lib.imap0 (index: part: { inherit index part; }) parts)
+      );
+      meta = builtins.fromTOML (builtins.head parsed.right).part;
+    in
+    if (builtins.length parts >= 3) then
+      meta
+    else
+      throw ''
+        TOML Frontmatter not found in README.md for module ${modulename}
+
+        Please add the following to the top of your README.md:
+
+        ---
+        description = "Your description here"
+        categories = [ "Your categories here" ]
+        features = [ "inventory" ]
+        ---
+        ...rest of your README.md...
+      '';
+in
+{
+  inherit
+    frontmatterOptions
+    getModulesSchema
+    getFrontmatter
+
+    checkConstraints
+    getRoles
+    ;
+}
--- a/lib/inventory/frontmatter/interface.nix
+++ b/lib/inventory/frontmatter/interface.nix
@@ -0,0 +1,86 @@
+{
+  lib,
+  specialArgs,
+  ...
+}:
+let
+  inherit (lib) mkOption types;
+in
+{
+  options = {
+    description = mkOption {
+      type = types.str;
+      description = ''
+        A Short description of the module.
+      '';
+    };
+    categories = mkOption {
+      default = [ "Uncategorized" ];
+      description = ''
+        Categories are used for Grouping and searching.
+
+        While initial oriented on [freedesktop](https://specifications.freedesktop.org/menu-spec/latest/category-registry.html) the following categories are allowed
+      '';
+      type = types.listOf (
+        types.enum [
+          "AudioVideo"
+          "Audio"
+          "Video"
+          "Development"
+          "Education"
+          "Game"
+          "Graphics"
+          "Social"
+          "Network"
+          "Office"
+          "Science"
+          "System"
+          "Settings"
+          "Utility"
+          "Uncategorized"
+        ]
+      );
+    };
+    features = mkOption {
+      default = [ ];
+      description = ''
+        Clans Features that the module implements support for.
+
+        !!! warning "Important"
+            Every ClanModule, that specifies `features = [ "inventory" ]` MUST have at least one role.
+            Many modules use `roles/default.nix` which registers the role `default`.
+
+            If you are a clan module author and your module has only one role where you cannot determine the name, then we would like you to follow the convention.
+      '';
+      type = types.listOf (
+        types.enum [
+          "experimental"
+          "inventory"
+        ]
+      );
+    };
+
+    constraints = mkOption {
+      default = { };
+      description = ''
+        Constraints for the module
+
+        The following example requires exactly one `server`
+        and supports up to `7` clients
+
+        ```md
+        ---
+        constraints.roles.server.eq = 1
+        constraints.roles.client.max = 7
+        ---
+        ```
+      '';
+      type = types.submoduleWith {
+        inherit specialArgs;
+        modules = [
+          ../constraints
+        ];
+      };
+    };
+  };
+}