Add extraDebug, lint

all-modules.nix

@@ -8,6 +8,7 @@
     ./modules/flake.nix
     ./modules/formatter.nix
     ./modules/legacyPackages.nix
+    ./modules/lint.nix
     ./modules/moduleWithSystem.nix
     ./modules/nixosConfigurations.nix
     ./modules/nixosModules.nix

dev/tests/eval-tests.nix

@@ -99,6 +99,17 @@ rec {
     config = { };
   };
 
+  lints = mkFlake
+    { inputs.self = { }; }
+    {
+      lint.messages = [ "a top level message" ];
+      systems = [ "x86_64-linux" "aarch64-darwin" ];
+      debug = true;
+      perSystem = {
+        lint.messages = [ "a per-system message" ];
+      };
+    };
+
   runTests = ok:
 
     assert empty == {
@@ -148,6 +159,12 @@ rec {
 
     assert flakeModulesDisable.test123 == "option123";
 
+    assert lints.debug.lint.messages == [
+      "a top level message"
+      "in perSystem.aarch64-darwin: a per-system message"
+      "in perSystem.x86_64-linux: a per-system message"
+    ];
+
     ok;
 
   result = runTests "ok";

modules/debug.nix

@@ -14,7 +14,7 @@ let
     removeAttrs
     ;
 
-  mkDebugConfig = { config, options, extendModules }: config // {
+  mkDebugConfig = { config, options, extendModules }: config // config.extraDebug // {
     inherit config;
     inherit (config) _module;
     inherit options;
@@ -52,6 +52,13 @@ in
         See [Expore and debug option values](../debug.html) for more examples.
       '';
     };
+    extraDebug = mkOption {
+      type = types.attrsOf types.raw;
+      default = { };
+      description = ''
+        Extra values to return the flake `debug` attribute (if that has been enabled).
+      '';
+    };
     perSystem = mkPerSystemOption
       ({ options, config, extendModules, ... }: {
         _file = ./formatter.nix;

modules/lint.nix

@@ -0,0 +1,61 @@
+{ config, flake-parts-lib, lib, ... }:
+let
+  inherit (flake-parts-lib)
+    mkPerSystemOption
+    ;
+in
+{
+  options = {
+    lint = {
+      messages = lib.mkOption {
+        type = lib.types.listOf lib.types.str;
+        default = [ ];
+        description = ''
+          Diagnostic messages that a flake author may or may not care about.
+
+          For example, a module might detect that it's used in a weird way, but
+          not be sure whether that's a mistake or not. Emitting a warning would
+          be too much, but with this option, the author can still find the
+          detected problem, by enabling [`debug`](#opt-debug) and querying
+          the `debug.lint.messages` flake attribute in `nix repl`.
+
+          This feature is not gated by an enable option, as performance does not
+          suffer from an unevaluated option.
+
+          There's also no option to upgrade to warnings, because that would make
+          evaluation dependent on rather many options, even if the caller only
+          needs one specific unrelated thing from the flake.
+          A more complex interface could attach the warnings to specific flake
+          attribute paths, but that's not implemented for now.
+        '';
+      };
+    };
+    perSystem = mkPerSystemOption
+      ({ ... }: {
+        options.lint.messages = lib.mkOption {
+          type = lib.types.listOf lib.types.str;
+          default = [ ];
+          description = ''
+            Diagnostic messages that a flake author may or may not care about.
+
+            These messages are added to the `debug.lint.messages` flake attribute,
+            when [`debug`](#opt-debug) is enabled.
+          '';
+        };
+      });
+  };
+  config = {
+    extraDebug.lint.toplevel.messages = config.lint.messages;
+    extraDebug.lint.messages =
+      config.lint.messages ++
+      lib.concatLists (
+        lib.mapAttrsToList
+          (sysName: sys:
+            map
+              (msg: "in perSystem.${sysName}: ${msg}")
+              sys.lint.messages
+          )
+          config.allSystems
+      );
+  };
+}