Nest every integration under lib.caisson.<target> with uniform names

README.md

@@ -30,8 +30,8 @@ fit together instead of colliding.
 
 ## Quick start
 
-Use `caisson-core.mkLib` to compose your library, then `mkFlake` to
-produce the flake outputs. By convention, your primary configuration
+Use `caisson-core.mkLib` to compose your library, then
+`lib.caisson.flake-parts.mkConfiguration` to produce the flake outputs. By convention, your primary configuration
 lives in `configs/flake-parts/<flake-name>`.
 
 ```nix
@@ -43,7 +43,7 @@ lives in `configs/flake-parts/<flake-name>`.
 
       # Compose a library: the machinery lands under lib.caisson-core,
       # and caisson's flake-parts integration overlay contributes
-      # lib.caisson (mkFlake and friends).
+      # lib.caisson (one namespace per integration target).
       lib = caisson.lib.caisson-core.mkLib {
         inherit inputs;
 
@@ -52,8 +52,8 @@ lives in `configs/flake-parts/<flake-name>`.
           flake = {
             # The flake-parts modules this flake defines: closed over your
             # inputs, importable here, exportable to downstream consumers.
-            default = lib.caisson.mkFlakeModule ./modules/flake-parts/default;
-            # other = lib.caisson.mkFlakeModule inputs.other-flake.flakeModules.default;
+            default = lib.caisson.flake-parts.mkModule ./modules/flake-parts/default;
+            # other = lib.caisson.flake-parts.mkModule inputs.other-flake.flakeModules.default;
           };
         };
 
@@ -71,10 +71,10 @@ lives in `configs/flake-parts/<flake-name>`.
 
       };
 
-    in lib.caisson.mkFlake {
+    in lib.caisson.flake-parts.mkConfiguration {
 
       # Convention: your primary config lives in configs/flake-parts/<flake-name>
-      configModule = lib.caisson.mkFlakeModule ./configs/flake-parts/my-flake;
+      configModule = lib.caisson.flake-parts.mkModule ./configs/flake-parts/my-flake;
 
       # Select which modules (yours or your dependencies') this flake composes.
       moduleImports = modules: { inherit (modules) default; };

docs/development/testing-architecture.md

@@ -150,8 +150,8 @@ lib = inputs.caisson-core.lib.caisson-core.mkLib {
   };
 };
 
-lib.caisson.mkFlake {
-  configModule = lib.caisson.mkFlakeModule ./configs/flake-parts/unit-tests;
+lib.caisson.flake-parts.mkConfiguration {
+  configModule = lib.caisson.flake-parts.mkModule ./configs/flake-parts/unit-tests;
 };
 ```
 
@@ -163,7 +163,7 @@ overlay files register from that path because a flake cannot reference files
 outside its own source tree.
 
 The tests are not only testing library functions in isolation; the composition
-and `mkFlake` path is the same one a downstream consumer exercises, so they
+and `lib.caisson.flake-parts.mkConfiguration` path is the same one a downstream consumer exercises, so they
 verify that the framework's composition machinery works end-to-end.
 
 ### nix-unit integration
@@ -213,7 +213,7 @@ appear to a consumer.
 ### Purpose
 
 Integration test flakes verify that caisson works correctly when consumed as a
-dependency: that `mkLib`, `mkFlake`, class-keyed module registration, and
+dependency: that `mkLib`, `lib.caisson.flake-parts.mkConfiguration`, class-keyed module registration, and
 module composition behave as expected from a consumer's perspective.
 
 ### Structure
@@ -222,7 +222,7 @@ Each integration test is a standalone flake under `tests/integration/<name>/` th
 
 1. Takes `parent` (caisson's evaluated outputs, from the pool) as an input
 2. Calls `parent.lib.caisson-core.mkLib { inherit inputs; ... }` to bootstrap
-3. Uses `lib.caisson.mkFlake` to compose a flake
+3. Uses `lib.caisson.flake-parts.mkConfiguration` to compose a flake
 4. Defines a `checks.<system>.<name>` derivation that succeeds if composition
    worked
 

examples/literate-flake/flake.nix

@@ -56,7 +56,7 @@
           project's exported overlays and modules become available under
           `<project>/<name>`, and the usual selections pick from them per
           item. Registering caisson this way brings in its integrations
-          (`lib.caisson`, mkFlake included) and its exported modules.
+          (`lib.caisson`, the flake-parts one included) and its exported modules.
         - `modules` is a function from the composed `lib`, used to register
           this flake's own class-keyed modules.
         - `libOverlays` is a function from an input-closed `mkLibOverlay`
@@ -73,7 +73,7 @@
 
         modules = lib: {
           # Demonstrate class-keyed module registration.
-          # This class is not imported by mkFlake in this example.
+          # This class is not imported by the flake-parts mkConfiguration in this example.
           generic = {
             noop = lib.caisson-core.mkModule "generic" ({ ... }: { });
           };
@@ -82,7 +82,7 @@
             # takes the closure attrset ({ closure-inputs, closure-lib,
             # mkModule, ... }) as its first arg list; files that don't need it
             # take `{ ... }:`.
-            default = lib.caisson.mkFlakeModule ./modules/flake-parts/default;
+            default = lib.caisson.flake-parts.mkModule ./modules/flake-parts/default;
           };
         };
 
@@ -96,7 +96,7 @@
     /*
       Step 2: Create the flake outputs.
 
-      `mkFlake` wraps flake-parts' mkFlake, injecting the framework's core
+      `lib.caisson.flake-parts.mkConfiguration` wraps flake-parts' mkFlake, injecting the framework's core
       module and threading `lib` as a special arg so modules receive
       the fully composed library.
 
@@ -108,8 +108,8 @@
         ("caisson/default" is caisson's default module, providing
         configInfo and the export options).
     */
-    lib.caisson.mkFlake {
-      configModule = lib.caisson.mkFlakeModule ./configs/flake-parts/literate-flake;
+    lib.caisson.flake-parts.mkConfiguration {
+      configModule = lib.caisson.flake-parts.mkModule ./configs/flake-parts/literate-flake;
 
       moduleImports = modules: [
         modules."caisson/default"

examples/literate-flake/modules/flake-parts/default/default.nix

@@ -2,7 +2,7 @@
 /*
   A flake module defines options, config, and per-system outputs.
 
-  Because mkFlake threads the composed `lib` as a special arg, modules
+  Because lib.caisson.flake-parts.mkConfiguration threads the composed `lib` as a special arg, modules
   receive the full library -- including overlays registered by this flake.
   Here we use `lib.literate-flake.greet` which was added by our library overlay.
 

flake.nix

@@ -70,7 +70,7 @@
 
           modules = composedLib: {
             flake = {
-              default = composedLib.caisson.mkFlakeModule ./modules/flake-parts/default;
+              default = composedLib.caisson.flake-parts.mkModule ./modules/flake-parts/default;
               # flake-parts' partitions module, registered so consumers
               # can select it from the registry instead of declaring a
               # flake-parts input of their own.
@@ -79,8 +79,8 @@
               # registry (nixpkgs-interface) and the package-set
               # machinery that reifies `caisson.nixpkgs.pkgSets` per
               # system (nixpkgs, which imports the interface).
-              nixpkgs = composedLib.caisson.mkFlakeModule ./modules/flake-parts/nixpkgs;
-              nixpkgs-interface = composedLib.caisson.mkFlakeModule ./modules/flake-parts/nixpkgs-interface;
+              nixpkgs = composedLib.caisson.flake-parts.mkModule ./modules/flake-parts/nixpkgs;
+              nixpkgs-interface = composedLib.caisson.flake-parts.mkModule ./modules/flake-parts/nixpkgs-interface;
             };
           };
 
@@ -100,11 +100,11 @@
       in
       let
 
-        flakeOutputs = lib.caisson.mkFlake {
+        flakeOutputs = lib.caisson.flake-parts.mkConfiguration {
 
           name = "caisson";
 
-          configModule = lib.caisson.mkFlakeModule ./configs/flake-parts/caisson;
+          configModule = lib.caisson.flake-parts.mkModule ./configs/flake-parts/caisson;
 
           moduleImports = modules: [
             modules.default

lib-overlays/check-args.nix

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MIT
+#
+# Every integration's entry point takes exactly the caisson-shaped
+# arguments (configModule, moduleImports, specialArgs, pkgSets,
+# ecosystemSrc, and a target's own few) and composes the evaluator's
+# call from them. Nothing else is forwarded: an evaluator argument
+# handed in directly would be silently overwritten, silently dropped,
+# or surface as a conflict deep inside the evaluator. The
+# `...WithEcosystemArgs` twin of each entry point is the way to the
+# evaluator's full surface: it takes the same arguments plus
+# `ecosystemArgs`, merged over the composed call verbatim, last.
+#
+# context:  the entry point, for the message.
+# accepted: the argument names it takes.
+# hints:    per-name pointers for the common mistakes (an evaluator
+#           name where a caisson name exists).
+# open:     the twin's name, or null when checking the twin itself.
+{
+  context,
+  accepted,
+  hints ? { },
+  open ? null,
+}:
+args:
+let
+  unknown = builtins.filter (name: !(builtins.elem name accepted)) (builtins.attrNames args);
+  name = builtins.head unknown;
+  message =
+    if hints ? ${name} then
+      "${context} does not accept `${name}`: ${hints.${name}}"
+    else if open != null then
+      "${context} does not accept `${name}`; it takes ${builtins.concatStringsSep ", " accepted}. The evaluator's own arguments are available through ${open}, in `ecosystemArgs`."
+    else
+      "${context} does not accept `${name}`; it takes ${builtins.concatStringsSep ", " accepted}. Evaluator arguments go in `ecosystemArgs`.";
+in
+if unknown == [ ] then args else throw message