feat: diff preview, structured renderers, dag template, test coverage (#2)

* feat: add diff preview and json/toml/yaml renderers

Diff app (nix run .#diff-files) shows what the writer would change
without writing. Supports --verbose for full diffs via difftastic.

Structured data options on files.file: json, toml, yaml serialize Nix
values directly — no pkgs.writers.* boilerplate needed.

* feat: add dag demo template for composing files across modules

Shows how multiple flake-parts modules can each contribute sections
to a README with ordering constraints (entryBefore, entryAfter,
entryBetween), then wire the dag-rendered output into files.file.

* style: fix deadnix and statix warnings, format all files

- Remove unused psArgs binding (deadnix)
- Use inherit instead of assignment (statix W04)
- Group repeated keys into attrsets (statix W20)
- Fix dag template URL to denful/dag
- Format all files with treefmt

* fix: enforce mutual exclusivity for text/json/toml/yaml, fix diff /dev/null

* chore: add .worktrees to gitignore

* fix: enable-false test must run writer before checking

* fix: use shellcheck-safe pattern for negated test

Author: sini

.gitignore

@@ -1,2 +1,4 @@
+
+.worktrees
 /.pre-commit-config.yaml
 result

README.md

@@ -62,7 +62,11 @@ it across [den](https://github.com/denful/den)'s template ecosystem:
 - **Works with and without flake-parts** — `flakeModule` for flake-parts,
   `module` for vanilla flakes via `evalModules`
 - **`files.file` convenience API** — `environment.etc`-style attrset with
-  `text` and `source` options
+  `text`, `source`, `json`, `toml`, and `yaml` options
+- **Structured data renderers** — `json`, `toml`, and `yaml` options
+  serialize Nix values directly, no `pkgs.writers.*` boilerplate
+- **Diff preview** — `nix run .#diff-files` shows what would change
+  without writing; `--verbose` for full diffs
 - **[treefmt-nix](https://github.com/numtide/treefmt-nix) integration** —
   `files.treefmt.enable` formats all entries through `nix fmt`
 - **Formatters** — global `files.formatters` by extension and per-file
@@ -82,6 +86,7 @@ Working examples live in [`templates/`](templates/):
 - [`flake-parts`](templates/flake-parts/) — flake-parts + import-tree with treefmt, global formatters, per-file overrides, onChange hooks, and both APIs
 - [`bare-flake`](templates/bare-flake/) — vanilla flake using `evalModules`, no flake-parts dependency
 - [`no-flake`](templates/no-flake/) — pure `default.nix` with `import`, no flake infrastructure
+- [`dag`](templates/dag/) — composing a single file from sections across multiple modules using [dag](https://github.com/theutz/dag) for topological ordering
 
 ## Quick start
 
@@ -116,8 +121,10 @@ Working examples live in [`templates/`](templates/):
 ```
 
 ```sh
-nix run .#write-files   # write files to disk
-nix flake check         # verify they match
+nix run .#write-files       # write files to disk
+nix run .#diff-files        # preview what would change
+nix run .#diff-files -- -v  # preview with full diffs
+nix flake check             # verify they match
 ```
 
 ## With treefmt
@@ -217,6 +224,9 @@ the project root. Use slashes for subdirectories.
 | ------------ | ------------------------------------ | ------- | ------------------------------------------------------------------------------- |
 | `enable`     | `bool`                               | `true`  | Set `false` to suppress this file.                                              |
 | `text`       | `nullOr lines`                       | `null`  | Inline text content. Sets `source` automatically.                               |
+| `json`       | `nullOr anything`                    | `null`  | JSON value to serialize. Sets `source` automatically.                           |
+| `toml`       | `nullOr anything`                    | `null`  | TOML value to serialize. Sets `source` automatically.                           |
+| `yaml`       | `nullOr anything`                    | `null`  | YAML value to serialize. Sets `source` automatically.                           |
 | `source`     | `path`                               | —       | Path or derivation for the file content.                                        |
 | `executable` | `bool`                               | `false` | `chmod +x` after writing.                                                       |
 | `onChange`   | `str` or `{ runtimeInputs, script }` | `""`    | Shell commands run after all files are written. Runs under `set -euo pipefail`. |
@@ -245,6 +255,14 @@ perSystem = { config, pkgs, ... }: {
     };
   };
 
+  # structured data — no pkgs.writers.* boilerplate
+  files.file."data/config.json".json = { version = 1; debug = false; };
+  files.file."data/settings.toml".toml = { database.host = "localhost"; };
+  files.file."data/compose.yaml".yaml = {
+    version = "3";
+    services.app.image = "myapp:latest";
+  };
+
   # disable a file defined by a shared module
   files.file."docs/internal.md".enable = false;
 
@@ -316,9 +334,11 @@ files.files = [
 | -------------------- | ----------------- | --------------- | ----------------------------------------------------------------------------------------------------- |
 | `root`               | `path`            | —               | Root for check comparisons. Auto-set to `self` via flake-parts; set `root = self;` in vanilla flakes. |
 | `relativeRoot`       | `str`             | `""`            | Subdir from git root for the writer.                                                                  |
-| `generateApp`        | `bool`            | `false`         | Expose writer as `nix run .#write-files`.                                                             |
+| `generateApp`        | `bool`            | `false`         | Expose writer and diff as `nix run .#write-files` / `nix run .#diff-files`.                           |
 | `writer.exeFilename` | `singleLineStr`   | `"write-files"` | Writer executable name.                                                                               |
 | `writer.drv`         | `package`         | _(computed)_    | The writer derivation (read-only).                                                                    |
+| `diff.exeFilename`   | `singleLineStr`   | `"diff-files"`  | Diff executable name.                                                                                 |
+| `diff.drv`           | `package`         | _(computed)_    | The diff derivation (read-only). Shows what would change without writing.                             |
 | `checks`             | `attrsOf package` | _(computed)_    | Per-file check derivations (read-only).                                                               |
 
 ## Without flake-parts

flake-module.nix

@@ -16,12 +16,16 @@
         files.treefmt.package = lib.mkIf (config.files.treefmt.enable && options.formatter.isDefined) (
           lib.mkDefault config.formatter
         );
-        checks = config.files.checks;
+        inherit (config.files) checks;
         apps = lib.mkIf config.files.generateApp {
           ${config.files.writer.exeFilename} = {
             type = "app";
             program = lib.getExe config.files.writer.drv;
           };
+          ${config.files.diff.exeFilename} = {
+            type = "app";
+            program = lib.getExe config.files.diff.drv;
+          };
         };
       };
     }

module.nix

@@ -150,11 +150,34 @@ in
                     Sets `source` automatically via `pkgs.writeText`.
                   '';
                 };
+                json = lib.mkOption {
+                  type = lib.types.nullOr lib.types.anything;
+                  default = null;
+                  description = ''
+                    JSON value to serialize. Sets `source` automatically.
+                  '';
+                };
+                toml = lib.mkOption {
+                  type = lib.types.nullOr lib.types.anything;
+                  default = null;
+                  description = ''
+                    TOML value to serialize. Sets `source` automatically.
+                  '';
+                };
+                yaml = lib.mkOption {
+                  type = lib.types.nullOr lib.types.anything;
+                  default = null;
+                  description = ''
+                    YAML value to serialize. Sets `source` automatically.
+                    Requires `pkgs.yj` for JSON-to-YAML conversion.
+                  '';
+                };
                 source = lib.mkOption {
                   type = lib.types.path;
                   description = ''
                     Path or derivation to use as the file content.
-                    Set automatically when `text` is provided.
+                    Set automatically when `text`, `json`, `toml`, or `yaml`
+                    is provided.
                   '';
                 };
                 executable = lib.mkOption {
@@ -198,7 +221,30 @@ in
                   '';
                 };
               };
-              config.source = lib.mkIf (config.text != null) (pkgs.writeText name config.text);
+              config.source =
+                let
+                  contentSources = lib.filter (x: x != null) [
+                    config.text
+                    config.json
+                    config.toml
+                    config.yaml
+                  ];
+                in
+                assert lib.assertMsg (
+                  builtins.length contentSources <= 1
+                ) "files.file.\"${name}\": only one of text, json, toml, yaml may be set";
+                if config.text != null then
+                  pkgs.writeText name config.text
+                else if config.json != null then
+                  pkgs.writers.writeJSON name config.json
+                else if config.toml != null then
+                  (pkgs.formats.toml { }).generate name config.toml
+                else if config.yaml != null then
+                  pkgs.runCommand name { nativeBuildInputs = [ pkgs.yj ]; } ''
+                    yj -jy < ${pkgs.writers.writeJSON name config.yaml} > $out
+                  ''
+                else
+                  lib.mkDefault config.source;
             }
           )
         );
@@ -272,11 +318,24 @@ in
           readOnly = true;
         };
       };
+
+      diff = {
+        exeFilename = lib.mkOption {
+          type = lib.types.singleLineStr;
+          default = "diff-files";
+          description = "The diff executable filename.";
+        };
+        drv = lib.mkOption {
+          description = "The diff executable derivation (read-only).";
+          type = lib.types.package;
+          readOnly = true;
+        };
+      };
     };
   };
 
-  config = {
-    files.files =
+  config.files = {
+    files =
       let
         toListEntry =
           name:
@@ -299,7 +358,7 @@ in
       lib.mapAttrsToList toListEntry enabledFiles;
 
     # apply formatting to all files.files entries (both attrset and list API)
-    files._formattedFiles =
+    _formattedFiles =
       let
         extOf =
           name:
@@ -336,12 +395,8 @@ in
             formatter =
               if format != null then
                 format
-              else if cfg.formatters ? ${ext} then
-                cfg.formatters.${ext}
-              else if cfg.treefmt.enable then
-                treefmtFormat
               else
-                null;
+                cfg.formatters.${ext} or (if cfg.treefmt.enable then treefmtFormat else null);
           in
           (removeAttrs entry [ "format" ])
           // {
@@ -350,7 +405,7 @@ in
       in
       map applyFormat cfg.files;
 
-    files.writer.drv =
+    writer.drv =
       let
         formattedFiles = cfg._formattedFiles;
         activeHooks = builtins.filter ({ onChange, ... }: onChange.script != "") formattedFiles;
@@ -417,7 +472,77 @@ in
             lib.concatLines ([ preamble ] ++ writeCommands ++ onChangeHooks);
       };
 
-    files.checks = lib.pipe cfg._formattedFiles [
+    diff.drv =
+      let
+        formattedFiles = cfg._formattedFiles;
+
+        preamble = ''
+          cd "$(git rev-parse --show-toplevel)"
+        ''
+        + lib.optionalString (cfg.relativeRoot != "") ''
+          cd ${lib.escapeShellArg cfg.relativeRoot}
+        '';
+
+        diffCommands = map (
+          { path, drv, ... }:
+          let
+            escapedPath = lib.escapeShellArg path;
+          in
+          ''
+            if ! [ -f ${escapedPath} ]; then
+              echo "  create ${path}"
+              _changes=$((_changes + 1))
+              if [ "$_verbose" = 1 ]; then
+                cat ${drv}
+              fi
+            elif ! cmp -s ${drv} ${escapedPath}; then
+              echo "  update ${path}"
+              _changes=$((_changes + 1))
+              if [ "$_verbose" = 1 ]; then
+                difft --display inline ${escapedPath} ${drv} || true
+              fi
+            else
+              echo "  ok     ${path}"
+            fi
+          ''
+        ) formattedFiles;
+      in
+      pkgs.writeShellApplication {
+        name = cfg.diff.exeFilename;
+        runtimeInputs = [
+          pkgs.gitMinimal
+          pkgs.difftastic
+        ];
+        derivationArgs = {
+          allowSubstitutes = false;
+          preferLocalBuild = true;
+        };
+        text =
+          if formattedFiles == [ ] then
+            ''echo "No files configured. Add entries to files.file or files.files."''
+          else
+            ''
+              _changes=0
+              _verbose=0
+              for arg in "$@"; do
+                case "$arg" in
+                  -v|--verbose) _verbose=1 ;;
+                esac
+              done
+            ''
+            + preamble
+            + lib.concatLines diffCommands
+            + ''
+              if [ "$_changes" -eq 0 ]; then
+                echo "All files up to date."
+              else
+                echo "$_changes file(s) would change."
+                exit 1
+              fi
+            '';
+      };
+
+    checks = lib.pipe cfg._formattedFiles [
       (map (
         { path, drv, ... }:
         {

templates/bare-flake/flake.nix

@@ -19,37 +19,43 @@
         modules = [
           files.module
           {
-            config._module.args = {
-              inherit pkgs;
-            };
-            config.files.root = self;
+            config = {
+              _module.args = {
+                inherit pkgs;
+              };
+              files = {
+                root = self;
 
-            # --- files.file attrset API ---
-            config.files.file.".gitignore".text = ''
-              result
-              .direnv
-            '';
+                # --- files.file attrset API ---
+                file = {
+                  ".gitignore".text = ''
+                    result
+                    .direnv
+                  '';
 
-            config.files.file."README.md".text = ''
-              # bare-flake demo
-              Uses `evalModules` with `files.module` directly.
-            '';
+                  "README.md".text = ''
+                    # bare-flake demo
+                    Uses `evalModules` with `files.module` directly.
+                  '';
 
-            config.files.file."scripts/hello.sh" = {
-              text = ''
-                #!/bin/sh
-                echo "hello from bare flake!"
-              '';
-              executable = true;
-            };
+                  "scripts/hello.sh" = {
+                    text = ''
+                      #!/bin/sh
+                      echo "hello from bare flake!"
+                    '';
+                    executable = true;
+                  };
+                };
 
-            # --- files.files list API ---
-            config.files.files = [
-              {
-                path = "data/version.txt";
-                drv = pkgs.writeText "version.txt" "0.1.0";
-              }
-            ];
+                # --- files.files list API ---
+                files = [
+                  {
+                    path = "data/version.txt";
+                    drv = pkgs.writeText "version.txt" "0.1.0";
+                  }
+                ];
+              };
+            };
           }
         ];
       };

templates/ci/modules/dogfood.nix

@@ -3,9 +3,11 @@
   perSystem =
     { config, ... }:
     {
-      files.root = inputs.files;
-      files.generateApp = true;
-      files.treefmt.enable = true;
+      files = {
+        root = inputs.files;
+        generateApp = true;
+        treefmt.enable = true;
+      };
       make-shells.default.packages = [ config.files.writer.drv ];
     };
 }

templates/ci/modules/gitignore.nix

@@ -11,7 +11,10 @@
       ];
   };
   config = {
-    gitignore = "result";
+    gitignore = ''
+      .worktrees
+      result
+    '';
     perSystem =
       { pkgs, ... }:
       {