Tooling

Four repositories support the gen libraries. They are not libraries themselves, and the hub does not include them.

gen-harness

The test harness every gen library’s CI is built from. A library’s ci/flake.nix calls gen-harness.lib.mkCi and gets a nix-unit test suite, treefmt, a dev shell and pre-commit hooks:

{
  inputs = {
    gen-harness.url = "github:sini/gen-harness";
    nixpkgs.url = "https://channels.nixos.org/nixos-unstable/nixexprs.tar.xz";
  };

  outputs =
    inputs@{ gen-harness, ... }:
    gen-harness.lib.mkCi {
      inherit inputs;
      name = "gen-schema";
      testModules = ./tests;
      specialArgs = { genSchema = import ../lib; };
    };
}

A test module sets flake.tests.<suite>.<name> = { expr; expected; };. Run a library’s suites from its root with:

nix develop ./ci --command ci

This command fails if a file under the test directories is unknown to git. Nix evaluates a git-filtered copy of the repository, so an untracked test file would otherwise be skipped without any message.

The dev shell also provides relock, which moves the repository’s flake.lock and ci/flake.lock to the latest revision of every input. relock <input> moves one input.

gen-harness also holds the CI workflow every library calls. It runs the library’s checks under three evaluators: upstream Nix, Determinate Nix and Lix. See Trust.

gen-demo

An acceptance corpus. gen-demo uses the hub the way a framework does, through flakeModules.default and flakeModules.genLibs, and holds small declarations that use the libraries together. It configures no real machine. Its CI fails when two libraries that pass their own tests stop working together.

gen-lsp

Editor and agent support. gen-lsp reads a configuration’s options, aspects and gen library functions, and produces the option tree a nixd worker uses for hovers and completions, plus a JSON listing an MCP server can give to coding agents. It depends on no gen library and no nixpkgs.lib.

gen-differential

Machinery for differential tests, which check that two implementations agree. Each comparison takes both implementations as arguments, states the claim it checks, and records every disagreement by name. gen-merge uses it to test its module system against nixpkgs’ lib.evalModules.