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-tests/find-cycles.cc

@@ -0,0 +1,115 @@
+#include "nix/store/build/find-cycles.hh"
+#include "nix/store/dependency-graph.hh"
+
+#include <gtest/gtest.h>
+#include <ranges>
+
+namespace nix {
+
+/**
+ * Parameters for DependencyGraph cycle detection tests
+ */
+struct FindCyclesParams
+{
+    std::string description;
+    std::vector<std::pair<std::string, std::string>> inputEdges; // (from, to) pairs
+    std::vector<std::vector<std::string>> expectedCycles;
+
+    friend std::ostream & operator<<(std::ostream & os, const FindCyclesParams & params)
+    {
+        os << "Test: " << params.description << "\n";
+        os << "Input edges (" << params.inputEdges.size() << "):\n";
+        for (const auto & [from, to] : params.inputEdges) {
+            os << "  " << from << " -> " << to << "\n";
+        }
+        os << "Expected cycles (" << params.expectedCycles.size() << "):\n";
+        for (const auto & cycle : params.expectedCycles) {
+            os << "  ";
+            for (size_t i = 0; i < cycle.size(); ++i) {
+                if (i > 0)
+                    os << " -> ";
+                os << cycle[i];
+            }
+            os << "\n";
+        }
+        return os;
+    }
+};
+
+class FindCyclesTest : public ::testing::TestWithParam<FindCyclesParams>
+{};
+
+namespace {
+// Comparator for sorting cycles deterministically
+bool compareCycles(const std::vector<std::string> & a, const std::vector<std::string> & b)
+{
+    if (a.size() != b.size())
+        return a.size() < b.size();
+    return std::lexicographical_compare(a.begin(), a.end(), b.begin(), b.end());
+}
+} // namespace
+
+TEST_P(FindCyclesTest, FindCycles)
+{
+    const auto & params = GetParam();
+
+    // Build graph from input edges
+    FilePathGraph depGraph;
+    for (const auto & [from, to] : params.inputEdges) {
+        depGraph.addEdge(from, to);
+    }
+
+    // Find cycles - returns vector<vector<string>> directly!
+    auto actualCycles = depGraph.findCycles();
+
+    EXPECT_EQ(actualCycles.size(), params.expectedCycles.size()) << "Number of cycles doesn't match expected";
+
+    // Sort both for comparison using ranges (order may vary, but content should match)
+    std::ranges::sort(actualCycles, compareCycles);
+    auto expectedCycles = params.expectedCycles;
+    std::ranges::sort(expectedCycles, compareCycles);
+
+    // Compare each cycle
+    EXPECT_EQ(actualCycles, expectedCycles);
+}
+
+INSTANTIATE_TEST_CASE_P(
+    FindCycles,
+    FindCyclesTest,
+    ::testing::Values(
+        // Empty input - no cycles
+        FindCyclesParams{"empty input", {}, {}},
+
+        // Single edge - no cycle
+        FindCyclesParams{"single edge no cycle", {{"a", "b"}}, {}},
+
+        // Simple cycle: A->B, B->A
+        FindCyclesParams{"simple cycle", {{"a", "b"}, {"b", "a"}}, {{"a", "b", "a"}}},
+
+        // Complete cycle: A->B->C->A
+        FindCyclesParams{"three node cycle", {{"a", "b"}, {"b", "c"}, {"c", "a"}}, {{"a", "b", "c", "a"}}},
+
+        // Four node cycle: A->B->C->D->A
+        FindCyclesParams{
+            "four node cycle", {{"a", "b"}, {"b", "c"}, {"c", "d"}, {"d", "a"}}, {{"a", "b", "c", "d", "a"}}},
+
+        // Multiple disjoint cycles
+        FindCyclesParams{
+            "multiple disjoint cycles",
+            {{"a", "b"}, {"b", "a"}, {"c", "d"}, {"d", "c"}},
+            {{"a", "b", "a"}, {"c", "d", "c"}}},
+
+        // Cycle with non-cycle edges (A->B->A is cycle, C->D is not)
+        FindCyclesParams{"cycle with extra edges", {{"a", "b"}, {"b", "a"}, {"c", "d"}}, {{"a", "b", "a"}}},
+
+        // Self-loop
+        FindCyclesParams{"self-loop", {{"a", "a"}}, {{"a", "a"}}},
+
+        // Chain without cycle
+        FindCyclesParams{"chain no cycle", {{"a", "b"}, {"b", "c"}, {"c", "d"}}, {}},
+
+        // Complex: cycle with incoming/outgoing edges
+        // X->A->B->C->A (only A->B->C->A is the cycle)
+        FindCyclesParams{"cycle with tail", {{"x", "a"}, {"a", "b"}, {"b", "c"}, {"c", "a"}}, {{"a", "b", "c", "a"}}}));
+
+} // namespace nix

src/libstore-tests/meson.build

@@ -62,6 +62,7 @@ sources = files(
   'derived-path.cc',
   'downstream-placeholder.cc',
   'dummy-store.cc',
+  'find-cycles.cc',
   'http-binary-cache-store.cc',
   'legacy-ssh-store.cc',
   'local-binary-cache-store.cc',

src/libstore/build/find-cycles.cc

@@ -0,0 +1,57 @@
+#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;
+               for (size_t i = 0; i < cycle.size() - 1; ++i) {
+                   cycleWithFiles.emplace_back(cycle[i].to_string());
+
+                   // Add file annotations for this edge
+                   for (auto & fileAnnotation : annotateEdgeWithFiles(cycle[i], cycle[i + 1])) {
+                       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',