feat: support nested commands option

Author: deemp

modules/commands.nix

@@ -1,28 +1,40 @@
 { lib, config, pkgs, ... }:
 let
-  inherit (import ../nix/commands/devshell.nix { inherit pkgs; }) commandsToMenu commandToPackage devshellMenuCommandName;
-  inherit (import ../nix/commands/types.nix { inherit pkgs; }) commandsFlatType;
+  inherit (import ../nix/commands/lib.nix { inherit pkgs; })
+    commandsType
+    commandToPackage
+    devshellMenuCommandName
+    commandsToMenu
+    ;
 in
 {
   options.commands = lib.mkOption {
-    type = commandsFlatType;
+    type = commandsType;
     default = [ ];
     description = ''
       Add commands to the environment.
     '';
     example = lib.literalExpression ''
-      [
-        {
-          help = "print hello";
-          name = "hello";
-          command = "echo hello";
-        }
-
-        {
-          package = "nixpkgs-fmt";
-          category = "formatter";
-        }
-      ]
+      {
+        packages = [
+          "diffutils"
+          "goreleaser"
+        ];
+        scripts = [
+          {
+            prefix = "nix run .#";
+            inherit packages;
+          }
+          {
+            name = "nix fmt";
+            help = "format Nix files";
+          }
+        ];
+        utilites = [
+          [ "GitHub utility" "gitAndTools.hub" ]
+          [ "golang linter" "golangci-lint" ]
+        ];
+      }
     '';
   };
 
@@ -40,6 +52,10 @@ in
 
   # Add the commands to the devshell packages. Either as wrapper scripts, or
   # the whole package.
-  config.devshell.packages = map commandToPackage config.commands;
+  config.devshell.packages =
+    lib.filter
+      (x: x != null)
+      (map commandToPackage config.commands);
+
   # config.devshell.motd = "$(motd)";
 }

modules/modules-docs.nix

@@ -47,6 +47,8 @@ let
     in
     map (p: repack (unpack p));
 
+  mkUrl = root: path: "${root.url}/tree/${root.branch}/${path}";
+
   # Transforms a module path into a (path, url) tuple where path is relative
   # to the repo root, and URL points to an online view of the module.
   mkDeclaration =
@@ -69,7 +71,7 @@ let
     else
       rec {
         path = removePrefix root.prefix decl;
-        url = "${root.url}/tree/${root.branch}/${path}";
+        url = mkUrl root path;
       };
 
   # Sort modules and put "enable" and "package" declarations first.
@@ -80,7 +82,7 @@ let
       compareWithPrio = pred: cmp: splitByAndCompare pred compare cmp;
       moduleCmp = compareWithPrio isEnable (compareWithPrio isPackage compare);
     in
-    compareLists moduleCmp a.loc b.loc < 0;
+    compareLists moduleCmp (map toString a.loc) (map toString b.loc) < 0;
 
   # Replace functions by the string <function>
   substFunction = x:
@@ -114,11 +116,22 @@ let
       )
   );
 
+  inherit (import ../nix/commands/lib.nix { inherit pkgs; }) mkLocSuffix nestedOptionsType flatOptionsType;
+
   # TODO: display values like TOML instead.
   toMarkdown = optionsDocs:
     let
-      optionsDocsPartitioned = partition (opt: head opt.loc != "_module") optionsDocs;
-
+      optionsDocsPartitionedIsMain = partition (opt: head opt.loc != "_module") optionsDocs;
+      nixOnlyLocPrefix = [ "commands" "<name>" ];
+      optionsDocsPartitionedIsNixOnly = partition (opt: (take 2 opt.loc) == nixOnlyLocPrefix) optionsDocsPartitionedIsMain.right;
+      nixOnly = optionsDocsPartitionedIsNixOnly.right;
+      nixOnlyPartitionedIsTop = partition (opt: opt.loc == nixOnlyLocPrefix ++ [ "*" ]) nixOnly;
+      nixOnlyPartitionedHasSuffix = partition (opt: ("${last opt.loc}" == "${mkLocSuffix nestedOptionsType.name}")) nixOnlyPartitionedIsTop.wrong;
+      nixOnlyOrdered = nixOnlyPartitionedIsTop.right ++ nixOnlyPartitionedHasSuffix.right ++ nixOnlyPartitionedHasSuffix.wrong;
+      nixAndTOMLOrdered = optionsDocsPartitionedIsNixOnly.wrong;
+      nixExtra = optionsDocsPartitionedIsMain.wrong;
+      concatOpts = opts: (concatStringsSep "\n\n" (map optToMd opts));
+      
       # TODO: handle opt.relatedPackages. What is it for?
       optToMd = opt:
         let heading = (lib.showOption (filter isString opt.loc)) + (concatStrings (filter (x: !(isString x)) opt.loc)); in
@@ -165,13 +178,30 @@ let
               opt.declarations
             )
         )
-        + "\n"
       ;
       doc = [
-        "## Options\n"
-        (concatStringsSep "\n" (map optToMd optionsDocsPartitioned.right))
-        "## Extra options\n"
-        (concatStringsSep "\n" (map optToMd optionsDocsPartitioned.wrong))
+        "# Options\n"
+        "## Available only in `Nix`\n"
+        (
+          let
+            root = head cfg.roots;
+            pathExamples = "nix/commands/examples.nix";
+            pathExamplesReal = ../${pathExamples};
+            pathCommandsLib = "tests/extra/commands.lib.nix";
+            pathCommandsLibReal = ../${pathCommandsLib};
+            mkLink = path: "[link](${mkUrl root path})";
+          in
+          assert lib.assertMsg (lib.pathExists pathExamplesReal) "Path `${pathExamplesReal} doesn't exist.`";
+          assert lib.assertMsg (lib.pathExists pathCommandsLibReal) "Path `${pathCommandsLibReal} doesn't exist.`";
+          ''
+            See how `commands.<name>` (${mkLink pathExamples}) maps to `commands.*` (${mkLink pathCommandsLib}).
+          ''
+        )
+        (concatOpts nixOnlyOrdered)
+        "## Available in `Nix` and `TOML`\n"
+        (concatOpts nixAndTOMLOrdered)
+        "## Extra options available only in `Nix`\n"
+        (concatOpts nixExtra)
       ];
     in
     concatStringsSep "\n" doc;

nix/commands/examples.nix

@@ -0,0 +1,87 @@
+{ system ? builtins.currentSystem
+, pkgs ? import ../nixpkgs.nix { inherit system; }
+}:
+let inherit (pkgs) lib; in
+{
+  nested = {
+    "category 1" = [
+      {
+        prefix = "nix run .#";
+        prefixes = {
+          a.b = {
+            d = "nix run ../#";
+          };
+        };
+        packages = {
+          a.b = {
+            jq-1 = [ "[package] jq description" pkgs.jq ];
+            yq-1 = pkgs.yq-go;
+            yq-2 = pkgs.yq-go;
+          };
+          npm = "nodePackages.npm";
+        };
+        help = "[package] default description";
+        helps = {
+          a.b = {
+            jq-1 = "[package] another jq description";
+            yq-1 = "[package] yq description";
+          };
+        };
+      }
+      {
+        packages.a.b = { inherit (pkgs) hyperfine findutils; };
+        expose = true;
+        exposes.a.b.hyperfine = false;
+      }
+      {
+        commands.a.b.awk = ''${lib.getExe pkgs.gawk} $@'';
+        helps.a.b.awk = "[command] run awk";
+
+        commands.a.b.jq-2 = [ "[command] run jq" "${lib.getExe pkgs.jq} $@" ];
+
+        commands."command with spaces" = ''printf "hello\n"'';
+        helps."command with spaces" = ''[command] print "hello"'';
+      }
+      pkgs.python3
+      [ "[package] vercel description" "nodePackages.vercel" ]
+      "nodePackages.yarn"
+      {
+        package = pkgs.gnugrep;
+      }
+      {
+        name = "run cowsay";
+        help = "run hello";
+        package = "cowsay";
+      }
+      {
+        name = "run perl";
+        help = "run perl";
+        command = "${lib.getExe pkgs.perl} $@";
+      }
+      {
+        name = "nix fmt";
+        help = "format Nix files";
+      }
+    ];
+    category-2 = [
+      {
+        package = pkgs.go;
+      }
+      [ "[package] run hello " "hello" ]
+      pkgs.nixpkgs-fmt
+    ];
+  };
+
+  flat = [
+    {
+      category = "scripts";
+      package = "black";
+    }
+    [ "[package] print hello" "hello" ]
+    "nodePackages.yarn"
+
+    # uncomment to trigger errors:
+    # [ "a" ]
+    # [ "a" "b" "c" ]
+  ];
+}

nix/commands/lib.nix

@@ -0,0 +1,6 @@
+{ system ? builtins.currentSystem
+, pkgs ? import ../nixpkgs.nix { inherit system; }
+}:
+(import ./types.nix { inherit pkgs; }) //
+(import ./devshell.nix { inherit pkgs; }) //
+(import ./typesCommands.nix { inherit pkgs; })