If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/NixOS/nix shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 11 active contributors
• Distributed ownership (top contributor 39% of recent commits)
• LGPL-2.1 licensed
• CI configured
• Tests present
• ⚠ LGPL-2.1 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live NixOS/nix repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/NixOS/nix.

What it runs against: a local clone of NixOS/nix — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in NixOS/nix | Confirms the artifact applies here, not a fork | | 2 | License is still LGPL-2.1 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of NixOS/nix. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/NixOS/nix.git
#   cd nix
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of NixOS/nix and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "NixOS/nix(\\.git)?\\b" \\
  && ok "origin remote is NixOS/nix" \\
  || miss "origin remote is not NixOS/nix (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(LGPL-2\\.1)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"LGPL-2\\.1\"" package.json 2>/dev/null) \\
  && ok "license is LGPL-2.1" \\
  || miss "license drift — was LGPL-2.1 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/NixOS/nix"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Nix is a purely functional package manager for Linux and Unix systems that enables reproducible and declarative software deployment. It treats packages as immutable values derived from pure functions, storing each package in a content-addressed store (/nix/store) to guarantee bit-for-bit reproducibility across machines and time. Core capability: build packages from declarative Nix language expressions, with dependency graphs resolved automatically and bit-identical results guaranteed for the same inputs. Monolithic C++ codebase organized by subsystem: src/ likely contains the evaluator, store manager, and language runtime; doc/manual/ holds Markdown/Nix documentation with code generation (generate-builtins.nix, generate-settings.nix); ci/gha/ defines GitHub Actions test suites; contrib/ includes utility scripts. Build system uses Meson (118K lines of configuration). Language lexing/parsing via Lex (11K) and Yacc (24K) in src/.

Systems engineers, DevOps practitioners, and NixOS users who need reproducible builds and deployments; open-source contributors maintaining the Nix language runtime, evaluator, and package manager CLI; researchers in declarative systems and functional approaches to configuration management.

Nix is production-ready and actively developed: the codebase is 5+ MLOC in C++ with comprehensive CI (GitHub Actions workflows in .github/workflows/), established contributor guidelines (CONTRIBUTING.md, HACKING.md), and a decade-plus history as Eelco Dolstra's PhD research. The repo shows active maintenance with multiple workflows (ci.yml, backport.yml, labeler.yml) and structured testing infrastructure (ci/gha/tests/).

Nix has significant complexity: 5.2M lines of C++, 631K lines of Shell, and intricate dependency resolution logic in the evaluator and store layer. The codebase uses Yacc/Lex for language parsing (24K/11K lines), adding maintenance overhead. Breaking changes can ripple through the Nixpkgs ecosystem (500K+ packages). Single points of failure exist in core subsystems (store, evaluator) that affect reproducibility guarantees.

Active development visible in CI workflows (ci.yml runs comprehensive checks), backport automation (.github/workflows/backport.yml suggests release management), and structured issue templates (.github/ISSUE_TEMPLATE/) for bugs/features/installer problems. Documentation is being actively generated (expand-includes.py, generate-builtins.nix), indicating ongoing language feature documentation. Dependabot enabled (.github/dependabot.yml) for dependency tracking.

1. Clone the repo: git clone https://github.com/NixOS/nix.git && cd nix
2. Follow development setup from HACKING.md or https://nix.dev/manual/nix/development/development/building.html (uses Nix itself to provision dev environment: nix develop)
3. Build: meson setup build && meson compile -C build (Meson is primary build system)
4. Run tests: meson test -C build

Daily commands: After meson setup build: meson compile -C build produces the nix binary. Run with ./build/src/nix/nix --help. For development iteration: meson compile -C build then ./build/src/nix/nix (outputs to build/). Run tests with meson test -C build. Rebuild evaluator after editing src/libexpr/*: meson compile -C build.

• src/libexpr/eval.cc: Core Nix language evaluator implementing lazy evaluation, thunk forcing, and function application—heart of the system
• src/libstore/store-api.cc: Abstract store interface defining how derivations are built and stored; central to reproducibility guarantees
• src/libexpr/parser.cc: Nix language parser (paired with lexer.l); any syntax changes require editing this file
• src/nix/command.cc: CLI command dispatcher; entry point for nix subcommands like build, shell, flake
• doc/manual/generate-builtins.nix: Auto-generates documentation for all Nix builtin functions from the C++ implementation
• .clang-format: Code style enforced across 5M+ lines of C++; violating this blocks PRs
• .github/workflows/ci.yml: Main CI pipeline running tests, builds, and linters on every PR—defines what passes
• HACKING.md: Developer onboarding guide with build/test instructions specific to Nix's Meson setup

Language features: edit src/libexpr/parser.cc, src/libexpr/lexer.l, src/libexpr/eval.cc; add builtins in doc/manual/generate-builtins.nix or src/libexpr/builtins.cc. Store/derivation logic: src/libstore/store-api.cc, src/libstore/derivations.cc. CLI commands: src/nix/command.cc and src/nix/commands/.cc. Documentation: doc/manual/src/ markdown files; regenerate with generate-.py scripts. Tests: ci/gha/tests/ has integration tests; add unit tests alongside modified .cc files. Build config: meson.build files (start at root meson.build).

Nix bootstrapping: Nix uses itself to build; nix develop requires Nix already installed on your system (use nix.dev installer or use VM). Pure evaluation mode: tests may use --pure-eval which disallows file access; environment variables must be explicit. Store path semantics: /nix/store paths are immutable and content-addressed; modifying src/ doesn't invalidate existing store paths (can cause stale test data). Lexer/parser regeneration: editing src/libexpr/lexer.l or parser.y requires Meson to regenerate C++ (automatic but can cause confusing rebuild failures). Flakes vs. legacy: codebase supports both Nix expression syntax and experimental flakes; some features only in one mode. Version in .version: hardcoded version string; releases require manual bump.

• Content-Addressed Store & Derivations — Nix's core guarantee: every package's /nix/store path is determined by hashing its inputs (sources + dependencies); understanding derivations as immutable values is prerequisite to understanding Nix's reproducibility model
• Lazy Evaluation (Thunks & Forcing) — Nix evaluates expressions lazily to enable recursive package sets and infinite data structures; src/libexpr/eval.cc implements thunk forcing; critical for performance and avoiding unnecessary computation
• Purely Functional Programming in Package Management — Nix treats packages as pure functions (f: inputs → output); no side effects means identical inputs always produce identical outputs, enabling reproducibility—this is the philosophical foundation differentiating Nix from traditional package managers
• Fixed-Point Semantics (Recursive Sets) — Nix's rec { ... } and overlays use fixed-point recursion to enable self-referential packages; Nixpkgs's entire dependency graph relies on this; src/libexpr/ implements fixed-point evaluation
• Realizing Derivations (Build Execution) — Derivations are lazy descriptions; realization executes the actual build; src/libstore/store-api.cc handles the realize operation, managing sandboxing and caching—core to Nix's reproducibility guarantee
• Lexical Scoping with Dynamic Shadowing — Nix's let-bindings and function parameters use lexical scope but allow dynamic override via with expressions; src/libexpr/parser.cc and eval.cc implement this non-standard scoping model
• Binary Caching & Substitution — Nix stores pre-built binaries in binary caches (e.g., cache.nixos.org) keyed by derivation hash; src/libstore/ implements cache lookups to avoid rebuilding; critical for adoption in CI/CD

• NixOS/nixpkgs — The canonical package repository (500K+ Nix expressions) that provides all packages Nix can build; users of nix/nix consume this
• NixOS/nixos — NixOS Linux distribution configured entirely via Nix; demonstrates Nix used as a system package manager and declarative OS builder
• tweag/nickel — Modern reimagining of the Nix language with better ergonomics; shares the same purely-functional package philosophy and interoperates with Nix
• numtide/flake-utils — Companion library (Nix expressions) that simplifies Nix flakes; widely used by Nix developers to reduce boilerplate
• input-output-hk/haskell.nix — Specialized Nix package set for Haskell; demonstrates how Nix enables language-specific reproducible builds

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for doc/manual generation scripts

The doc/manual directory contains several Python and shell scripts for documentation generation (generate-builtins.nix, generate-deps.py, generate-redirects.py, expand-includes.py, remove_before_wrapper.py, render-manpage.sh) but there's no visible test coverage for these critical build-time scripts. Adding unit tests would catch regressions in documentation builds early and improve maintainability.

• [ ] Create tests/unit/doc-generation/ directory structure
• [ ] Add pytest tests for doc/manual/generate-deps.py covering edge cases (missing deps, circular refs)
• [ ] Add pytest tests for doc/manual/expand-includes.py with various include patterns
• [ ] Add pytest tests for doc/manual/generate-redirects.py with malformed redirect configs
• [ ] Integrate tests into CI pipeline (ci/gha/tests/)
• [ ] Document test execution in HACKING.md

Implement GitHub Action workflow for validating doc/manual formatting and anchors

The doc/manual contains anchors.jq, custom.css, and quote-literals.xsl suggesting complex formatting requirements, but there's no pre-commit validation workflow beyond general CI. Adding a dedicated workflow would catch documentation formatting issues before merge, similar to the existing labels.yml and backport.yml workflows.

• [ ] Create .github/workflows/doc-validation.yml
• [ ] Add jq validation step for doc/manual/anchors.jq syntax
• [ ] Add XSL validation for doc/manual/quote-literals.xsl
• [ ] Run doc/manual/meson.build in dry-run mode to catch build errors early
• [ ] Add check for duplicate anchor IDs in generated manual
• [ ] Reference workflow in CONTRIBUTING.md

Add integration tests for release note generation pipeline (rl-next/)

The doc/manual/rl-next/ directory contains release note markdown fragments but there's no visible validation that these properly convert to the final release notes. Adding tests would ensure the release note generation process (which likely uses the generate-*.nix scripts) handles edge cases like malformed markdown, missing metadata, or duplicate entries.

• [ ] Create tests/integration/release-notes/ directory
• [ ] Add test fixtures with valid and invalid rl-next markdown files
• [ ] Write tests verifying all rl-next/*.md files have proper frontmatter/structure
• [ ] Test the aggregation process that combines rl-next entries into release notes
• [ ] Add test for proper ordering/categorization of release notes
• [ ] Integrate into ci/gha/tests/pre-commit-checks/ workflow

• Add missing builtins documentation: Several C++ builtins in src/libexpr/builtins.cc lack docstrings for auto-doc generation (doc/manual/generate-builtins.nix). Pick an unset builtin, add a docstring in the C++ code, and verify it appears in generated manual.
• Expand test coverage for store operations: src/libstore/ has core functionality (derivations.cc, store-api.cc) but ci/gha/tests/ lacks integration tests for content-addressing edge cases. Write a test that creates two derivations with identical inputs and verify they produce identical /nix/store paths.
• Improve error messages for parser errors: src/libexpr/parser.cc throws generic parse errors. Add source location (line:column) to at least 3 error paths, then write test cases in ci/gha/tests/ that check the improved messages are readable.

The NixOS/nix repository demonstrates good security practices with clear project structure, CI/CD pipelines, and documentation. However, a complete security assessment is limited by: (1) inability to analyze full source code from file structure alone, (2) missing dependency manifests for vulnerability scanning, and (3) incomplete visibility into build configurations and security settings. The project appears well-maintained with GitHub security features (CODEOWNERS, issue templates, CI workflows). Critical areas requiring attention: dependency vulnerability scanning, secrets scanning in CI/CD, and compilation security hardening flags. No obvious hardcoded credentials or injection vulnerabilities are evident from the file structure provided.

• Low · Git Blame Ignore Revisions File Present — .git-blame-ignore-revs. The presence of .git-blame-ignore-revs indicates commits that are commonly ignored in blame operations. While not a direct vulnerability, this requires ensuring that ignored commits don't contain security-critical changes that bypass review. Fix: Regularly audit the ignored revisions to ensure no security patches or critical fixes are being obscured from blame attribution.
• Low · Build Artifacts and Configuration Not Fully Visible — Build system configuration files (meson.build, meson.options). The Meson build system is used (meson.build, meson.options files visible), but complete build configuration cannot be fully analyzed from the provided file listing. This could potentially hide security misconfigurations in the build process. Fix: Ensure build system security review includes: no hardcoded credentials in build configs, proper sanitization flags enabled, security warnings treated as errors, and secure defaults for compilation flags.
• Low · Incomplete Dependency Information — Root directory and subdirectories. No package dependency files (package.json, Cargo.toml, requirements.txt, etc.) were provided in the file structure, making it impossible to assess known vulnerable dependencies. Fix: Perform full supply chain security analysis: scan all dependency manifests (C++ dependencies, Python scripts, Node.js if present) with tools like OWASP Dependency-Check, Snyk, or Trivy. Maintain an up-to-date SBOM (Software Bill of Materials).

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.