nix-tf-schema

Feature Specification: Entrypoint, Checks and Documentation

Created: 2026-09-22

Status: Implemented

Input: Reconstructed from the code at 3c0765d, default.nix, flake.nix, the .forgejo/workflows/, the md/ pages, the commit and pull request history of nix-tf-schema, and the Claude Code logs.

User Scenarios & Testing (mandatory)

User Story 1 - Use the library from a pin or from a flake (Priority: P1)

A consumer that pins nix-tf-schema with npins (or a plain fetchTarball) calls it with its own pkgs, so that the helpers evaluate against the consumer's nixpkgs. A flake consumer reads the same helpers from the flake outputs.

Why this priority: a library that brings its own nixpkgs into the evaluation of a consumer makes a second nixpkgs instance and types that do not match.

Independent Test: evaluate (pkgs.callPackage ./. { }).lib with a given pkgs, and (builtins.getFlake ...).lib. Both have the same helper names.

Acceptance Scenarios:

  1. Given a consumer pkgs, When the consumer calls default.nix with it, Then the helpers use that pkgs and that lib.
  2. Given no arguments, When a user imports default.nix, Then pkgs comes from the local npins pin.
  3. Given the flake, When a consumer reads lib, Then there is no system key, because the helpers are pure functions; checks, formatter, packages and devShells have a system key.

User Story 2 - Check a change (Priority: P1)

A contributor opens a pull request. CI runs the nix-unit suite, the format check and the documentation build.

Why this priority: the helpers are the public surface; a regression breaks every consumer.

Independent Test: run nix develop --command nix-unit ./conversion-test.nix and nix build .#checks.x86_64-linux.treefmt .#checks.x86_64-linux.docs.

Acceptance Scenarios:

  1. Given the nix-unit suite, When CI runs it, Then it runs outside the build sandbox, because test-extractProviderSchemas uses import-from-derivation.
  2. Given the flake checks, When a user runs nix flake check, Then only sandbox-safe checks run (treefmt, docs).
  3. Given the dev shell, When a contributor enters it, Then nix-unit and spec-kit are available.

User Story 3 - Read the documentation (Priority: P2)

A user reads a site with an overview, a comparison with other tools, one section per helper rendered from its doc-comment, and the flake outputs.

Why this priority: the helpers have many parameters, and the doc-comments are the reference.

Independent Test: build .#packages.x86_64-linux.docs. The site has the pages index, comparison, functions and flake-attributes, in that order.

Acceptance Scenarios:

  1. Given a doc-comment on a function in conversion.nix or lib.nix, When the site builds, Then the function has a section with the anchor function-library-tf-schema.<category>.<name>.
  2. Given the flake outputs, When the site builds, Then the flake-attributes page lists packages, checks and devShells from the entrypoint, so it cannot drift.

Edge Cases

  • lib is not listed on the flake-attributes page, because its helpers have no meta.description; the functions page documents them.
  • The CI workflow that publishes the site runs on main only.

Requirements (mandatory)

Functional Requirements

  • FR-001: default.nix MUST be the one entrypoint, callable by callPackage with pkgs and lib from the consumer.
  • FR-002: flake.nix MUST only add the system layer to default.nix and MUST expose lib without a system key.
  • FR-003: All inputs MUST be pinned with npins.
  • FR-004: The flake MUST give checks for the format and the documentation site, and a dev shell with nix-unit and spec-kit.
  • FR-005: CI MUST run the nix-unit suite, the format check and the documentation build on each pull request.
  • FR-006: The documentation site MUST render the doc-comment of each exported helper with nixdoc, through nix-docs-lib.
  • FR-007: Links between doc-comments MUST use the anchors that the site makes (#function-library-tf-schema.<category>.<name>), and each link MUST have a target.
  • FR-008: The README and the landing page MUST NOT give counts or lists of helpers or tests that can go out of date. They describe the capabilities and link to the function reference on the site.
  • FR-009: The documentation, comments and test data MUST describe the library by itself, not by a consumer (constitution principle I).

Key Entities

  • Entrypoint: default.nix, which returns lib, checks, packages, devShells, formatter, pkgs, sources and nix-unit.
  • Documentation site: the ndg site from md/ and the generated pages.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: The nix-unit, treefmt and docs CI jobs pass on main.
  • SC-002: A consumer that passes its own pkgs evaluates one nixpkgs instance.

Assumptions

  • nix-docs-lib stays the documentation tool, shared with other projects.
  • CI runs on Forgejo Actions with runners that have Nix.