feat(libstore): add detailed cycle detection for build errors

Implements comprehensive cycle detection that shows users exactly which
files create circular dependencies when a build fails. This dramatically
improves the developer experience when debugging dependency cycles.

## What's Added

**findCycles() Method** (dependency-graph-impl.hh):
- DFS-based cycle detection using BGL's depth_first_search
- Custom visitor that tracks back edges to identify cycles
- Returns all cycles found in the graph (not just the first one)
- Each cycle is represented as a path: [A, B, C, A]

**findDependencyCycles() Function** (build/find-cycles.hh):
High-level API for cycle detection in store paths:
1. Builds StorePath-level dependency graph via buildStorePathGraphFromScan()
2. Detects cycles using the DFS algorithm
3. Annotates each edge in the cycle with the files that created it
4. Returns human-readable cycle descriptions with file paths

Example output format:
```
Cycle 1:
  → /nix/store/abc-pkg-a
  (via /lib/libfoo.so)
  → /nix/store/def-pkg-b
  (via /bin/bar)
  → /nix/store/abc-pkg-a
```

**Enhanced Build Error Reporting** (derivation-builder.cc):
- Wraps output registration in try-catch blocks
- On cycle detection, calls analyzeCyclesAndThrow()
- Scans all outputs to find exact file locations
- Generates detailed error messages showing:
  * All cycles found (not just one)
  * Specific files creating each dependency
  * Helpful hints about preserved temp paths for debugging

**analyzeCyclesAndThrow() Helper**:
- Takes output path information and referenceable paths
- Invokes findDependencyCycles() on each output
- Aggregates all cycles across outputs
- Throws BuildError with comprehensive cycle details
- Falls back to original error if no detailed cycles found

## Comprehensive Testing

**find-cycles.cc**: Parameterized tests covering:
- Empty graphs and single edges (no cycles)
- Simple 2-node cycles: A→B→A
- Multi-node cycles: A→B→C→A, A→B→C→D→A
- Multiple disjoint cycles in same graph
- Self-loops: A→A
- Chains without cycles (negative cases)
- Complex graphs with cycles + non-cycle edges
- Cycles with additional incoming/outgoing edges

Uses GoogleTest's INSTANTIATE_TEST_CASE_P for comprehensive coverage.

## Implementation Notes

- **DFS Back-Edge Detection**: Standard algorithm for finding all cycles
  - Discovers vertices and tracks the DFS path
  - Back edges indicate cycles; extract path from stack
  - Finds all cycles in one traversal

- **File-Level Attribution**:
  - Uses FileListEdgeProperty to store file lists on edges
  - buildStorePathGraphFromScan() populates this during scanning
  - Enables showing "which file caused this dependency"

- **Error Recovery**: If scanForReferencesDeep fails to find detailed cycles,
  re-throws original exception rather than suppressing it

- **Performance**: Only runs detailed cycle analysis on error path,
  no overhead for successful builds

## User Experience

Before: "cycle detected in build of 'foo' in the references of output 'out' from output 'dev'"

After: Shows all cycles with file paths, making it immediately clear which
specific files need to be fixed to break the circular dependency.

This is part of the better-cycle-errors-v2 effort to improve Nix's
error messages for one of the most confusing build failure scenarios.

Author: lovesegfault

src/libstore/build/find-cycles.cc

@@ -0,0 +1,63 @@
+#include "nix/store/build/find-cycles.hh"
+
+#include "nix/store/store-api.hh"
+#include "nix/store/path-references.hh"
+#include "nix/store/dependency-graph.hh"
+#include "nix/util/source-accessor.hh"
+
+#include <filesystem>
+#include <ranges>
+
+namespace nix {
+
+std::vector<std::vector<std::string>>
+findDependencyCycles(const Path & path, const StorePath & storePath, const StorePathSet & refs)
+{
+    // Build a StorePath-level dependency graph using the unified helper
+    // The graph has edge properties containing file lists
+    auto accessor = getFSSourceAccessor();
+    auto depGraph = buildStorePathGraphFromScan(*accessor, CanonPath(path), storePath, refs);
+
+    // Find cycles at StorePath level - returns vector<vector<StorePath>>
+    auto cycles = depGraph.findCycles();
+
+    debug("findDependencyCycles: found %lu cycles", cycles.size());
+
+    // Convert cycles to strings, annotating with file details from edge properties
+    auto annotateEdgeWithFiles = [&](const StorePath & from, const StorePath & to) -> std::vector<std::string> {
+        std::vector<std::string> result;
+        auto edgeProp = depGraph.getEdgeProperty(from, to);
+        if (edgeProp && !edgeProp->files.empty()) {
+            for (const auto & file : edgeProp->files) {
+                result.push_back("  (via " + file.abs() + ")");
+            }
+        }
+        return result;
+    };
+
+    return cycles | std::views::transform([&](const auto & cycle) {
+               std::vector<std::string> cycleWithFiles;
+
+               // Process adjacent pairs of nodes using slide
+               for (const auto & window : cycle | std::views::slide(2)) {
+                   const auto & from = window[0];
+                   const auto & to = window[1];
+
+                   cycleWithFiles.emplace_back(from.to_string());
+
+                   // Add file annotations for this edge
+                   for (auto & fileAnnotation : annotateEdgeWithFiles(from, to)) {
+                       cycleWithFiles.push_back(std::move(fileAnnotation));
+                   }
+               }
+
+               // Add final node to close the cycle
+               if (!cycle.empty()) {
+                   cycleWithFiles.emplace_back(cycle.back().to_string());
+               }
+               return cycleWithFiles;
+           })
+           | std::ranges::to<std::vector>();
+}
+
+} // namespace nix

src/libstore/include/nix/store/build/find-cycles.hh

@@ -0,0 +1,31 @@
+#pragma once
+///@file
+
+#include "nix/store/store-api.hh"
+#include "nix/util/types.hh"
+
+#include <string>
+#include <vector>
+
+namespace nix {
+
+/**
+ * Find dependency cycles in output paths with detailed file locations.
+ *
+ * Uses scanForReferencesDeep to detect which files contain which references,
+ * builds a StorePath-level dependency graph using BGL, and uses DFS with back-edge
+ * detection to find all cycles.
+ *
+ * Returns both the cycle structure (at StorePath level) and file-level details showing
+ * which specific files created each dependency.
+ *
+ * @param path The filesystem path to scan (e.g., /nix/store/abc-foo)
+ * @param storePath The StorePath that this path represents
+ * @param refs The set of potentially referenced store paths
+ * @return Vector of cycles, where each cycle shows the StorePath dependencies annotated
+ *         with the specific files that created them
+ */
+std::vector<std::vector<std::string>>
+findDependencyCycles(const Path & path, const StorePath & storePath, const StorePathSet & refs);
+
+} // namespace nix

src/libstore/include/nix/store/meson.build

@@ -21,6 +21,7 @@ headers = [ config_pub_h ] + files(
   'build/derivation-resolution-goal.hh',
   'build/derivation-trampoline-goal.hh',
   'build/drv-output-substitution-goal.hh',
+  'build/find-cycles.hh',
   'build/goal.hh',
   'build/substitution-goal.hh',
   'build/worker.hh',

src/libstore/meson.build

@@ -267,6 +267,7 @@ sources = files(
   'build/derivation-trampoline-goal.cc',
   'build/drv-output-substitution-goal.cc',
   'build/entry-points.cc',
+  'build/find-cycles.cc',
   'build/goal.cc',
   'build/substitution-goal.cc',
   'build/worker.cc',

src/libstore/unix/build/derivation-builder.cc

@@ -4,7 +4,10 @@
 #include "nix/util/processes.hh"
 #include "nix/store/builtins.hh"
 #include "nix/store/path-references.hh"
+#include "nix/store/build/find-cycles.hh"
 #include "nix/util/finally.hh"
+
+#include <ranges>
 #include "nix/util/util.hh"
 #include "nix/util/archive.hh"
 #include "nix/util/git.hh"
@@ -62,6 +65,73 @@ struct NotDeterministic : BuildError
     }
 };
 
+/**
+ * Information about an output path for cycle analysis.
+ */
+struct OutputPathInfo
+{
+    std::string outputName; ///< Name of the output (e.g., "out", "dev")
+    StorePath storePath;    ///< The StorePath of this output
+    Path actualPath;        ///< Actual filesystem path where the output is located
+};
+
+/**
+ * Helper to analyze cycles and throw a detailed error.
+ *
+ * This function always throws - either the detailed cycle error or re-throws
+ * the original exception if no cycles are found.
+ *
+ * @param drvName The formatted name of the derivation being built
+ * @param referenceablePaths Set of paths to search for in the outputs
+ * @param getOutputPaths Callback returning output information to scan
+ */
+[[noreturn]] static void analyzeCyclesAndThrow(
+    std::string_view drvName,
+    const StorePathSet & referenceablePaths,
+    std::function<std::vector<OutputPathInfo>()> getOutputPaths)
+{
+    debug("cycle detected, analyzing for detailed error report");
+
+    // Scan all outputs for dependency cycles with exact file paths
+    std::vector<std::vector<std::string>> allCycles;
+    for (auto & output : getOutputPaths()) {
+        debug("scanning output '%s' at path '%s' for cycles", output.outputName, output.actualPath);
+
+        auto cycles = findDependencyCycles(output.actualPath, output.storePath, referenceablePaths);
+        // Move cycles to avoid copying the potentially large cycle data
+        std::ranges::move(cycles, std::back_inserter(allCycles));
+    }
+
+    if (allCycles.empty()) {
+        debug("no detailed cycles found, re-throwing original error");
+        throw;
+    }
+
+    debug("found %lu cycles", allCycles.size());
+
+    // Build detailed error message
+    std::string cycleDetails = fmt("Detailed cycle analysis found %d cycle path(s):", allCycles.size());
+
+    for (const auto & [idx, cycle] : std::views::enumerate(allCycles)) {
+        cycleDetails += fmt("\n\nCycle %d:", idx + 1);
+        for (auto & node : cycle) {
+            cycleDetails += fmt("\n  → %s", node);
+        }
+    }
+
+    cycleDetails +=
+        fmt("\n\nThis means there are circular references between output files.\n"
+            "The build cannot proceed because the outputs reference each other.");
+
+    // Add hint with temp paths for debugging
+    if (settings.keepFailed || verbosity >= lvlDebug) {
+        cycleDetails += "\n\nNote: Temporary build outputs are preserved for inspection.";
+    }
+
+    throw BuildError(
+        BuildResult::Failure::OutputRejected, "cycle detected in build of '%s': %s", drvName, cycleDetails);
+}
+
 /**
  * This class represents the state for building locally.
  *
@@ -1473,43 +1543,62 @@ SingleDrvOutputs DerivationBuilderImpl::registerOutputs()
         outputStats.insert_or_assign(outputName, std::move(st));
     }
 
-    auto sortedOutputNames = topoSort(
-        outputsToSort,
-        {[&](const std::string & name) {
-            auto orifu = get(outputReferencesIfUnregistered, name);
-            if (!orifu)
-                throw BuildError(
-                    BuildResult::Failure::OutputRejected,
-                    "no output reference for '%s' in build of '%s'",
-                    name,
-                    store.printStorePath(drvPath));
-            return std::visit(
-                overloaded{
-                    /* Since we'll use the already installed versions of these, we
-                       can treat them as leaves and ignore any references they
-                       have. */
-                    [&](const AlreadyRegistered &) { return StringSet{}; },
-                    [&](const PerhapsNeedToRegister & refs) {
-                        StringSet referencedOutputs;
-                        /* FIXME build inverted map up front so no quadratic waste here */
-                        for (auto & r : refs.refs)
-                            for (auto & [o, p] : scratchOutputs)
-                                if (r == p)
-                                    referencedOutputs.insert(o);
-                        return referencedOutputs;
-                    },
-                },
-                *orifu);
-        }},
-        {[&](const std::string & path, const std::string & parent) {
-            // TODO with more -vvvv also show the temporary paths for manual inspection.
-            return BuildError(
-                BuildResult::Failure::OutputRejected,
-                "cycle detected in build of '%s' in the references of output '%s' from output '%s'",
-                store.printStorePath(drvPath),
-                path,
-                parent);
-        }});
+    auto sortedOutputNames = [&]() {
+        try {
+            return topoSort(
+                outputsToSort,
+                {[&](const std::string & name) {
+                    auto orifu = get(outputReferencesIfUnregistered, name);
+                    if (!orifu)
+                        throw BuildError(
+                            BuildResult::Failure::OutputRejected,
+                            "no output reference for '%s' in build of '%s'",
+                            name,
+                            store.printStorePath(drvPath));
+                    return std::visit(
+                        overloaded{
+                            /* Since we'll use the already installed versions of these, we
+                               can treat them as leaves and ignore any references they
+                               have. */
+                            [&](const AlreadyRegistered &) { return StringSet{}; },
+                            [&](const PerhapsNeedToRegister & refs) {
+                                StringSet referencedOutputs;
+                                /* FIXME build inverted map up front so no quadratic waste here */
+                                for (auto & r : refs.refs)
+                                    for (auto & [o, p] : scratchOutputs)
+                                        if (r == p)
+                                            referencedOutputs.insert(o);
+                                return referencedOutputs;
+                            },
+                        },
+                        *orifu);
+                }},
+                {[&](const std::string & path, const std::string & parent) {
+                    // TODO with more -vvvv also show the temporary paths for manual inspection.
+                    return BuildError(
+                        BuildResult::Failure::OutputRejected,
+                        "cycle detected in build of '%s' in the references of output '%s' from output '%s'",
+                        store.printStorePath(drvPath),
+                        path,
+                        parent);
+                }});
+        } catch (std::exception & e) {
+            analyzeCyclesAndThrow(store.printStorePath(drvPath), referenceablePaths, [&]() {
+                std::vector<OutputPathInfo> outputPaths;
+                for (auto & [outputName, _] : drv.outputs) {
+                    auto scratchOutput = get(scratchOutputs, outputName);
+                    if (scratchOutput) {
+                        outputPaths.push_back(
+                            OutputPathInfo{
+                                .outputName = outputName,
+                                .storePath = *scratchOutput,
+                                .actualPath = realPathInSandbox(store.printStorePath(*scratchOutput))});
+                    }
+                }
+                return outputPaths;
+            });
+        }
+    }();
 
     std::reverse(sortedOutputNames.begin(), sortedOutputNames.end());
 
@@ -1848,12 +1937,24 @@ SingleDrvOutputs DerivationBuilderImpl::registerOutputs()
     /* Register each output path as valid, and register the sets of
        paths referenced by each of them.  If there are cycles in the
        outputs, this will fail. */
-    {
+    try {
         ValidPathInfos infos2;
         for (auto & [outputName, newInfo] : infos) {
             infos2.insert_or_assign(newInfo.path, newInfo);
         }
         store.registerValidPaths(infos2);
+    } catch (BuildError & e) {
+        analyzeCyclesAndThrow(store.printStorePath(drvPath), referenceablePaths, [&]() {
+            std::vector<OutputPathInfo> outputPaths;
+            for (auto & [outputName, newInfo] : infos) {
+                outputPaths.push_back(
+                    OutputPathInfo{
+                        .outputName = outputName,
+                        .storePath = newInfo.path,
+                        .actualPath = store.toRealPath(store.printStorePath(newInfo.path))});
+            }
+            return outputPaths;
+        });
     }
 
     /* If we made it this far, we are sure the output matches the