Flake schema docs

[edolstra]

Motivation

Update flake schema docs plus a few other improvements from NixOS#8892.

Context

---

Add 👍 to pull requests you find important.

The Nix maintainer team uses a GitHub project board to schedule and track reviews.

Summary by CodeRabbit

• Documentation

  • Expanded flake schema docs with a complete attribute table, defaults, and a new “Roles” section describing standard role names.

• Bug Fixes

  • Improved flake attribute resolution to tolerate type errors and continue resolution with fallback suggestions.

• Tests

  • Added functional test covering type-error fallback behavior during flake attribute resolution.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d680cb1d-747d-4958-bcb7-0deff8cd7c85

📥 Commits

Reviewing files that changed from the base of the PR and between 973fb95 and 7dc4d86.

📒 Files selected for processing (5)

• doc/manual/source/protocols/flake-schemas.md
• src/libcmd/installable-flake.cc
• src/libexpr/include/nix/expr/eval-cache.hh
• tests/functional/flakes/meson.build
• tests/functional/flakes/type-error-fallback.sh

✅ Files skipped from review due to trivial changes (3)

• tests/functional/flakes/meson.build
• doc/manual/source/protocols/flake-schemas.md
• src/libexpr/include/nix/expr/eval-cache.hh

🚧 Files skipped from review as they are similar to previous changes (2)

• src/libcmd/installable-flake.cc
• tests/functional/flakes/type-error-fallback.sh

---

📝 Walkthrough

Walkthrough

Adds TypeError handling to flake output attribute resolution (InstallableFlake::getCursors), makes AttrCursor members const, adds a functional test validating fallback behavior, and expands flake schema documentation with a Roles section and a full attribute table.

Changes

TypeError Fallback for Attribute Path Resolution

Layer / File(s)	Summary
Cursor data structure immutability src/libexpr/include/nix/expr/eval-cache.hh	AttrCursor members root and parent are now const-qualified, preventing post-construction mutation.
Error handling and functional test src/libcmd/installable-flake.cc, tests/functional/flakes/type-error-fallback.sh, tests/functional/flakes/meson.build	InstallableFlake::getCursors wraps outputs->findAlongAttrPath(attrPath) in a try/catch for TypeError, logging debug messages and continuing iteration. Adds a functional test and Meson test entry exercising fallback from packages.<system> to legacyPackages.<system>.

Flake Schema Documentation

Layer / File(s)	Summary
Schema attribute table and defaults doc/manual/source/protocols/flake-schemas.md	Replace partial schema table with a complete specification listing version, doc, allowIFD, inventory, roles, appendSystem, and defaultAttrPath and their defaults.
Roles declaration semantics doc/manual/source/protocols/flake-schemas.md	New Roles section defines how schemas declare supported operations via role attributes and enumerates standard role names used by Nix commands.

Sequence Diagram(s)

sequenceDiagram
  participant getCursors
  participant outputs_findAlongAttrPath
  participant TypeError
  participant debugLog
  participant cursorAccumulator
  getCursors->>outputs_findAlongAttrPath: resolve attrPath
  alt resolution succeeds
    outputs_findAlongAttrPath-->>getCursors: AttrCursor
    getCursors->>cursorAccumulator: add cursor
  else TypeError thrown
    outputs_findAlongAttrPath->>TypeError: type mismatch while resolving path
    TypeError->>debugLog: log debug message
    debugLog-->>getCursors: continue to next attrPath
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• lucperkins

Poem

A rabbit hops through attr paths with care,
When types mislead, I catch and skip a snare,
I nudge the cursor onward with a grin,
To legacy fields where the outputs win,
Soft debug traces guide the graceful spin. 🐇✨

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title 'Flake schema docs' is vague and generic, using non-descriptive language that doesn't convey meaningful information about the actual changeset beyond a single file.	Revise the title to be more specific and descriptive. Consider: 'Add flake schema documentation and type-error fallback handling' or similar to capture the main changes.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch flake-schema-docs

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 Infer (1.2.0)

src/libcmd/installable-flake.cc

src/libcmd/installable-flake.cc:1:10: fatal error: 'nix/store/globals.hh' file not found
1 | #include "nix/store/globals.hh"
| ^~~~~~~~~~~~~~~~~~~~~~
1 error generated.
Error: the following clang command did not run successfully:
/opt/infer-linux-x86_64-v1.2.0/lib/infer/facebook-clang-plugins/clang/install/bin/clang-18
@/tmp/coderabbit-infer/7dc4d864e6a2bc860db8974d8d9b2d7b0dbe251e-8152bc6ead8b6584/tmp/clang_command_.tmp.492fc4.txt
++Contents of '/tmp/coderabbit-infer/7dc4d864e6a2bc860db8974d8d9b2d7b0dbe251e-8152bc6ead8b6584/tmp/clang_command_.tmp.492fc4.txt':
"-cc1" "-load"
"/opt/infer-linux-x86_64-v1.2.0/lib/infer/infer/bin/../../facebook-clang-plugins/libtooling/build/FacebookClangPlugin.dylib"
"-add-plugin" "BiniouASTExporter" "-plugin-arg-BiniouASTExporter" "-"
"-plugin-arg-BiniouASTExporter" "PREPEND_CURRENT_DIR=1"
"-plugin-arg-BiniouASTExporter" "MAX_STRING_SIZE=65535" "-cc1" "-triple"
"x86_64-unknown-linux-gnu" "-emit-obj" "-

... [truncated 1104 characters] ...

all/lib/clang/18/include"
"-internal-isystem" "/usr/local/include" "-internal-isystem"
"/usr/lib/gcc/x86_64-linux-gnu/12/../../../../x86_64-linux-gnu/include"
"-internal-externc-isystem" "/usr/include/x86_64-linux-gnu"
"-internal-externc-isystem" "/include" "-internal-externc-isystem"
"/usr/include" "-Wno-ignored-optimization-argument" "-Wno-everything"
"-fdeprecated-macro" "-ferror-limit" "19" "-fgnuc-version=4.2.1"
"-fskip-odr-check-in-gmf" "-fcxx-exceptions" "-fexceptions"
"-D__GCC_HAVE_DWARF2_CFI_ASM=1" "-o"
"/tmp/coderabbit-infer/8152bc6ead8b6584/file.o" "-x" "c++"
"src/libcmd/installable-flake.cc" "-O0" "-fno-builtin" "-include"
"/opt/infer-linux-x86_64-v1.2.0/lib/infer/infer/bin/../lib/clang_wrappers/global_defines.h"
"-Wno-everything"

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🚀 Deployed on https://6a22ea6279a6ca0ffc92d2ca--determinate-nix.netlify.app

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@doc/manual/source/protocols/flake-schemas.md`:
- Line 19: The description for `defaultAttrPath` is missing a verb; update the
sentence to read clearly (e.g., "A default flake output attribute path suffix to
use. For example, `packages` will look for `default` if no attribute path is
given.") so the field `defaultAttrPath` has a grammatical, self-contained
explanation that includes the example.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bae8578e-c977-4276-99da-19e61b9dad53

📥 Commits

Reviewing files that changed from the base of the PR and between 722f4e1 and 973fb95.

📒 Files selected for processing (5)

• doc/manual/source/protocols/flake-schemas.md
• src/libcmd/installable-flake.cc
• src/libexpr/include/nix/expr/eval-cache.hh
• tests/functional/flakes/meson.build
• tests/functional/flakes/type-error-fallback.sh