woods 1.6.4 → 2.0.0.beta1

data/lib/woods/graph_analyzer.rb

@@ -23,12 +23,43 @@ module Woods
   class GraphAnalyzer
     # Types that are naturally root nodes and should not be flagged as orphans.
     # Framework and gem sources are consumed but never referenced by application code
-    # in the dependency graph's reverse index.
-    EXCLUDED_ORPHAN_TYPES = %i[rails_source gem_source].freeze
+    # in the dependency graph's reverse index. Package units (#280) declare
+    # boundaries via metadata and `:package_dependency` edges to other
+    # packages; nothing points back at a leaf package in the reverse index,
+    # so it would otherwise be flagged as dead code it is not.
+    EXCLUDED_ORPHAN_TYPES = %i[rails_source gem_source package].freeze
+
+    # How many rounds {#assign_orphaned_units} runs before it stops pulling
+    # unnamespaced units into clusters through other unnamespaced units. The
+    # loop already stops early on the first round that assigns nothing; this
+    # bounds the pathological case (a long chain of unnamespaced units, where
+    # each round advances the frontier by one) so clustering stays linear-ish
+    # on large graphs.
+    ORPHAN_ASSIGNMENT_ROUNDS = 10
+
+    # Edge labels that come from an Active Record association reflection.
+    # Only these can cross a database boundary through Rails itself.
+    ASSOCIATION_VIAS = %w[belongs_to has_many has_one has_and_belongs_to_many].freeze
+
+    # A dependency must change at least this many times more often than
+    # its dependent to be reported by {#volatile_dependencies}.
+    DEFAULT_VOLATILE_RATIO = 3.0
+
+    # A dependency with fewer commits in the last year than this is too
+    # young to judge; POODR's rule is about things that keep changing, and
+    # a class touched four times could be settling down.
+    VOLATILE_MIN_COMMITS = 5
+
+    # How many volatile-dependency entries {#analyze} keeps. Published as
+    # `stats[:volatile_dependencies_limit]` so a reader of the array alone
+    # can tell whether it was truncated (B-182).
+    DEFAULT_VOLATILE_LIMIT = 20
 
     # @param dependency_graph [DependencyGraph] The graph to analyze
-    def initialize(dependency_graph)
+    # @param volatile_ratio [Numeric] see {#volatile_dependencies}
+    def initialize(dependency_graph, volatile_ratio: DEFAULT_VOLATILE_RATIO)
       @graph = dependency_graph
+      @volatile_ratio = volatile_ratio.to_f
     end
 
     # ══════════════════════════════════════════════════════════════════════
@@ -49,7 +80,7 @@ module Woods
 
           dependents = @graph.dependents_of(identifier)
           result << identifier if dependents.empty?
-        end
+        end.sort
       end
     end
 
@@ -65,7 +96,7 @@ module Woods
         nodes.each_with_object([]) do |(identifier, _meta), result|
           dependencies = @graph.dependencies_of(identifier)
           result << identifier if dependencies.empty?
-        end
+        end.sort
       end
     end
 
@@ -86,10 +117,21 @@ module Woods
           identifier: identifier,
           type: meta[:type],
           dependent_count: dependents.size,
-          dependents: dependents
+          # Sorted for the same reason the outer list tie-breaks on identifier:
+          # `dependents_of` returns graph-registration order, so an incremental
+          # run that appended a dependent would publish a different hub entry
+          # for an identical graph.
+          dependents: dependents.sort
         }
       end
-      identifiers_with_dependents.max_by(limit) { |h| h[:dependent_count] }
+      # Tie-break on identifier. Without it, which of the (often many) nodes
+      # sharing a dependent count land inside the top-N depends on graph
+      # insertion order, so two extractions of the same tree could publish
+      # different hub lists (#164) — incremental runs append new nodes at the
+      # end where a full extraction interleaves them by extractor.
+      identifiers_with_dependents
+        .sort_by { |h| [-h[:dependent_count], h[:identifier].to_s] }
+        .first(limit)
     end
 
     # Detect circular dependency chains in the graph.
@@ -123,7 +165,11 @@ module Woods
       nodes = graph_nodes
       return [] if nodes.size < 3
 
-      node_ids = nodes.keys
+      # Sorted, not insertion-ordered: the seeded sample indexes into this
+      # list, so leaving it in graph order would make the sampled pairs (and
+      # therefore the bridge scores) depend on the order units happened to be
+      # registered in rather than on the graph's content (#164).
+      node_ids = nodes.keys.sort
       scores = Hash.new(0)
 
       # Sample random pairs of nodes for shortest-path computation.
@@ -154,6 +200,93 @@ module Woods
         end
     end
 
+    # Association and foreign-key edges whose two ends resolve to different
+    # databases (#280).
+    #
+    # Reads only node attributes (`database`, `table`, `foreign_key_tables`)
+    # and edge attributes (`through`, `through_db`, `disable_joins`), so an
+    # incremental run that loaded the graph from disk computes exactly what
+    # a full run does.
+    #
+    # Scoped to primary nodes: identifiers as registered in {#graph_nodes}.
+    # A variant, the non-primary type registered under an identifier that
+    # collides across types, is not walked separately. Association edges are
+    # read with `type: :model`, so a variant sharing the identifier under a
+    # different type cannot contribute a crossing that belongs to it alone.
+    #
+    # A foreign key never picks a target owner that lives in `from_db`, even
+    # when another database also owns the table: an owner in the source
+    # database means the key resolves locally, whatever else claims the same
+    # table name. Only when every owner sits outside `from_db`, in more than
+    # one other database, does the entry come back ambiguous.
+    #
+    # `kind`:
+    # * `join_through_across_databases`: a `has_many :through` where
+    #   `disable_joins` is false and `from_db`, `through_db`, and `to_db` are
+    #   not all equal (a nil `through_db` falls back to comparing the two
+    #   ends). Rails will try to JOIN across connections; this is the
+    #   Uchitelle rule.
+    # * `association_across_databases`: any other association edge across
+    #   databases, including a through with `disable_joins`.
+    # * `foreign_key_across_databases`: a database-level foreign key whose
+    #   target table's owner (or every owner, when ambiguous) lives in
+    #   another database.
+    #
+    # @return [Array<Hash>] sorted by from, to, via
+    def cross_database_edges
+      @cross_database_edges ||= begin
+        nodes = graph_nodes
+        owners = table_owners(nodes)
+        entries = nodes.keys.sort.flat_map do |identifier|
+          meta = nodes[identifier]
+          from_db = meta[:database]
+          next [] unless from_db
+
+          association_crossings(identifier, from_db, nodes) +
+            foreign_key_crossings(identifier, from_db, meta, owners)
+        end
+        # Whole-hash dedup, not a `[from, to, via]` key: an ambiguous foreign
+        # key entry carries `to: nil` regardless of which table it names, so
+        # two distinct ambiguous foreign keys on the same model would
+        # otherwise collapse into one.
+        entries.uniq.sort_by { |e| [e[:from], e[:to], e[:via]] }
+      end
+    end
+
+    # Edges that point at something changing much faster than the thing
+    # that depends on it: "depend on things that change less often than
+    # you do" (POODR ch. 3), made checkable because the graph now carries
+    # commit counts (#280).
+    #
+    # Report only, never a gate: young classes produce false positives, so
+    # dependencies with fewer than {VOLATILE_MIN_COMMITS} commits or a
+    # `new` change frequency are skipped. Ranked by the dependency's
+    # PageRank so the most-depended-on volatile unit comes first. `limit`
+    # caps what this method hands back; {#analyze}'s
+    # `stats[:volatile_dependency_count]` reports the full qualifying count
+    # regardless of `limit`, and `stats[:volatile_dependencies_limit]` reports
+    # the cap, so a reader of the array alone can tell it was truncated.
+    #
+    # @param limit [Integer] maximum entries
+    # @return [Array<Hash>] `{ from:, from_type:, to:, to_type:, via:, from_commits:, to_commits:, ratio:, pagerank: }`
+    def volatile_dependencies(limit: DEFAULT_VOLATILE_LIMIT)
+      all_volatile_dependencies.first(limit)
+    end
+
+    # Edges that cross a Packwerk package boundary the source package never
+    # declared (#280).
+    #
+    # Membership comes from the `package` node attribute (Task 8); a
+    # declaration comes from a package unit's own `:package_dependency`
+    # edges (Task 7). Both are graph-only, so a full and an incremental run
+    # compute the same report. Enforcement stays with `packwerk check` /
+    # `pks check`; this only makes the undeclared boundary visible.
+    #
+    # @return [Array<Hash>] `{ from:, from_type:, to:, to_type:, via:, from_package:, to_package: }`, sorted
+    def undeclared_package_edges
+      @undeclared_package_edges ||= compute_undeclared_package_edges
+    end
+
     # Group units into semantic domains using namespace prefixes and graph connectivity.
     #
     # Strategy:
@@ -191,13 +324,13 @@ module Woods
       merge_small_clusters(clusters, min_size)
 
       # Step 4: Enrich each cluster with hub, entry points, boundary edges
-      pagerank_scores = @graph.pagerank
+      pagerank_scores = self.pagerank_scores
       enrich_clusters(clusters, nodes, pagerank_scores)
 
       # Sort by member count descending
       clusters.values
               .select { |c| c[:members].any? }
-              .sort_by { |c| -c[:member_count] }
+              .sort_by { |c| [-c[:member_count], c[:name].to_s] }
     end
 
     # Full analysis report combining all structural metrics.
@@ -210,6 +343,9 @@ module Woods
       computed_hubs = hubs
       computed_cycles = cycles
       computed_bridges = bridges(limit: 10)
+      computed_cross_database = cross_database_edges
+      computed_volatile = volatile_dependencies
+      computed_undeclared = undeclared_package_edges
 
       {
         orphans: computed_orphans,
@@ -217,11 +353,18 @@ module Woods
         hubs: computed_hubs,
         cycles: computed_cycles,
         bridges: computed_bridges,
+        cross_database_edges: computed_cross_database,
+        volatile_dependencies: computed_volatile,
+        undeclared_package_edges: computed_undeclared,
         stats: {
           orphan_count: computed_orphans.size,
           dead_end_count: computed_dead_ends.size,
           hub_count: computed_hubs.size,
-          cycle_count: computed_cycles.size
+          cycle_count: computed_cycles.size,
+          cross_database_edge_count: computed_cross_database.size,
+          volatile_dependency_count: all_volatile_dependencies.size,
+          volatile_dependencies_limit: DEFAULT_VOLATILE_LIMIT,
+          undeclared_package_edge_count: computed_undeclared.size
         }
       }
     end
@@ -258,41 +401,72 @@ module Woods
     end
 
     # Assign units with no namespace prefix to their most-connected cluster.
+    #
+    # Order-free (EXTB-7). Each round scores *every* still-unassigned unit
+    # against one membership snapshot taken before the round, then applies all
+    # of that round's assignments at once. Assigning inside the scoring loop —
+    # as this did — let a unit whose only connection is another unnamespaced
+    # unit join a cluster or not depending on which of the two the graph
+    # happened to enumerate first, i.e. on registration order, which differs
+    # between a full and an incremental run.
+    #
+    # Rounds are bounded: each one either assigns at least one unit or ends the
+    # loop, and {ORPHAN_ASSIGNMENT_ROUNDS} caps how far a chain of unnamespaced
+    # units can pull its successors in. Units past that depth stay unassigned —
+    # deterministically, which is the property that matters here.
     def assign_orphaned_units(clusters, filtered_ids, _nodes)
       return if clusters.empty?
 
-      unassigned = filtered_ids.select { |id| cluster_prefix(id).nil? }
+      pending = filtered_ids.select { |id| cluster_prefix(id).nil? }.sort
 
-      unassigned.each do |id|
-        best_cluster = find_most_connected_cluster(id, clusters)
-        next unless best_cluster
+      ORPHAN_ASSIGNMENT_ROUNDS.times do
+        break if pending.empty?
 
-        clusters[best_cluster][:members] << id
-        clusters[best_cluster][:member_set].add(id)
+        membership = clusters.transform_values { |cluster| cluster[:member_set] }.freeze
+        assignments = pending.filter_map do |id|
+          best_cluster = find_most_connected_cluster(id, clusters.keys, membership)
+          [id, best_cluster] if best_cluster
+        end
+        break if assignments.empty?
+
+        assignments.each do |id, name|
+          clusters[name][:members] << id
+          clusters[name][:member_set].add(id)
+        end
+        pending -= assignments.map(&:first)
       end
     end
 
     # Find which cluster a unit has the most connections to.
-    def find_most_connected_cluster(identifier, clusters)
+    #
+    # @param identifier [String]
+    # @param cluster_names [Array<String>]
+    # @param membership [Hash{String => Set<String>}] name => members, read as
+    #   of the start of the assignment round (see {#assign_orphaned_units})
+    # @return [String, nil]
+    def find_most_connected_cluster(identifier, cluster_names, membership)
       connections = Hash.new(0)
 
       # Check forward edges (dependencies)
       @graph.dependencies_of(identifier).each do |dep|
-        clusters.each do |name, cluster|
-          connections[name] += 1 if cluster[:member_set].include?(dep)
+        cluster_names.each do |name|
+          connections[name] += 1 if membership[name].include?(dep)
         end
       end
 
       # Check reverse edges (dependents)
       @graph.dependents_of(identifier).each do |dep|
-        clusters.each do |name, cluster|
-          connections[name] += 1 if cluster[:member_set].include?(dep)
+        cluster_names.each do |name|
+          connections[name] += 1 if membership[name].include?(dep)
         end
       end
 
       return nil if connections.empty?
 
-      connections.max_by { |_, count| count }.first
+      # Tie-break on cluster name. `max_by` alone returns whichever equal-count
+      # cluster the hash happened to enumerate first, which is registration
+      # order — the one determinism hole left in this class.
+      connections.max_by { |name, count| [count, name] }.first
     end
 
     # Merge clusters smaller than min_size into their most-connected neighbor.
@@ -302,7 +476,7 @@ module Woods
         break if small.empty?
 
         # Merge the smallest cluster first
-        name, cluster = small.min_by { |_, c| c[:members].size }
+        name, cluster = small.min_by { |cluster_name, c| [c[:members].size, cluster_name] }
 
         # Find which other cluster this one connects to most
         target = find_merge_target(cluster, clusters, name)
@@ -331,17 +505,26 @@ module Woods
 
       return nil if connections.empty?
 
-      connections.max_by { |_, count| count }.first
+      # Tie-break on cluster name. `max_by` alone returns whichever equal-count
+      # cluster the hash happened to enumerate first, which is registration
+      # order — the one determinism hole left in this class.
+      connections.max_by { |name, count| [count, name] }.first
     end
 
     # Enrich clusters with hub, entry points, boundary edges, and type breakdown.
     def enrich_clusters(clusters, nodes, pagerank_scores)
       clusters.each_value do |cluster|
-        members = cluster[:members]
+        # Sorted, like orphans/dead_ends/hubs. Members accumulate in graph
+        # registration order, and an incremental run appends where a full
+        # extraction interleaves by extractor — so an unsorted list publishes
+        # a different cluster for an identical graph. Everything derived below
+        # (entry points, boundary edges) inherits this order too.
+        members = cluster[:members].sort
+        cluster[:members] = members
         member_set = cluster[:member_set]
 
         # Hub: highest PageRank within the cluster
-        hub_id = members.max_by { |id| pagerank_scores[id] || 0 }
+        hub_id = members.max_by { |id| [pagerank_scores[id] || 0, id] }
         cluster[:hub] = hub_id
 
         # Entry points: controllers and GraphQL resolvers in the cluster's dependents
@@ -353,7 +536,7 @@ module Woods
             entry_points.add(dep) if meta && entry_types.include?(meta[:type].to_s)
           end
         end
-        cluster[:entry_points] = entry_points.to_a
+        cluster[:entry_points] = entry_points.to_a.sort
 
         # Boundary edges: connections that cross cluster boundaries
         boundary = []
@@ -377,7 +560,8 @@ module Woods
           end
         end
         # Deduplicate and limit boundary edges
-        cluster[:boundary_edges] = boundary.uniq { |e| [e[:from], e[:to]] }.first(20)
+        cluster[:boundary_edges] = boundary.uniq { |e| [e[:from], e[:to]] }
+                                           .sort_by { |e| [e[:from].to_s, e[:to].to_s] }.first(20)
 
         # Type breakdown
         type_counts = members.each_with_object(Hash.new(0)) do |id, counts|
@@ -410,11 +594,196 @@ module Woods
       @graph_nodes ||= graph_data[:nodes]
     end
 
-    # Access graph forward edges from cached graph data.
+    # ──────────────────────────────────────────────────────────────────────
+    # Cross-database helpers
+    # ──────────────────────────────────────────────────────────────────────
+
+    # table name => { database name => sorted identifiers of the model nodes
+    # in that database owning it }. Sorted identifier iteration makes a
+    # table owned by several nodes in one database resolve to the same
+    # first identifier every run; nodes with no table or no database
+    # contribute no ownership claim.
+    #
+    # @param nodes [Hash]
+    # @return [Hash{String => Hash{String => Array<String>}}]
+    def table_owners(nodes)
+      nodes.keys.sort.each_with_object({}) do |identifier, owners|
+        node = nodes[identifier]
+        table = node[:table]
+        database = node[:database]
+        next unless table && database
+
+        by_database = (owners[table] ||= {})
+        (by_database[database] ||= []) << identifier
+      end
+    end
+
+    # @return [Array<Hash>] association edges from `identifier` that land in another database
+    def association_crossings(identifier, from_db, nodes)
+      @graph.edge_records(identifier, type: :model).filter_map do |edge|
+        via = edge[:via].to_s
+        next unless ASSOCIATION_VIAS.include?(via)
+
+        target = nodes[edge[:target]]
+        to_db = target && target[:database]
+        through_db = edge[:through] ? edge[:through_db] : nil
+        databases = [from_db, to_db, through_db].compact.uniq
+        next if databases.size < 2
+
+        disable_joins = edge[:disable_joins] == true
+        kind = edge[:through] && !disable_joins ? 'join_through_across_databases' : 'association_across_databases'
+        {
+          from: identifier, to: edge[:target], via: via, from_db: from_db, to_db: to_db,
+          through: edge[:through], through_db: through_db, disable_joins: disable_joins, kind: kind
+        }
+      end
+    end
+
+    # @return [Array<Hash>] foreign keys from `identifier`'s table into a table owned by another database
+    def foreign_key_crossings(identifier, from_db, meta, owners)
+      Array(meta[:foreign_key_tables]).filter_map do |table|
+        foreign_key_crossing(identifier, from_db, table, owners)
+      end
+    end
+
+    # A single foreign key's crossing entry, or nil when an owner of `table`
+    # lives in `from_db` (the key resolves locally regardless of what else
+    # claims the table name) or when no node claims the table at all.
+    #
+    # @return [Hash, nil]
+    def foreign_key_crossing(identifier, from_db, table, owners)
+      by_database = owners[table]
+      return nil if by_database.nil? || by_database.key?(from_db)
+
+      base = {
+        from: identifier, via: 'foreign_key', from_db: from_db,
+        through: nil, through_db: nil, disable_joins: false, kind: 'foreign_key_across_databases'
+      }
+      databases = by_database.keys.sort
+      if databases.size == 1
+        owner_db = databases.first
+        base.merge(to: by_database[owner_db].first, to_db: owner_db)
+      else
+        base.merge(to: nil, to_db: nil, ambiguous_owners: by_database.values.flatten.sort)
+      end
+    end
+
+    # ──────────────────────────────────────────────────────────────────────
+    # Volatile dependency helpers
+    # ──────────────────────────────────────────────────────────────────────
+
+    # PageRank computed once per analyzer instance.
+    #
+    # @return [Hash{String => Float}]
+    def pagerank_scores
+      @pagerank_scores ||= @graph.pagerank
+    end
+
+    # Every qualifying edge, unranked by {#volatile_dependencies}'s `limit`.
+    # {#analyze} needs the full count separately from the persisted top 20.
+    #
+    # @return [Array<Hash>] sorted by pagerank, ratio, from, to, via
+    def all_volatile_dependencies
+      @all_volatile_dependencies ||= compute_volatile_dependencies
+    end
+
+    # Short-circuits to `[]`, skipping the PageRank computation entirely,
+    # when no node carries an Integer `commit_count` (git enrichment never
+    # ran): there is nothing to rank.
+    #
+    # @return [Array<Hash>]
+    def compute_volatile_dependencies
+      nodes = graph_nodes
+      return [] unless nodes.each_value.any? { |meta| meta[:commit_count].is_a?(Integer) }
+
+      scores = pagerank_scores
+      entries = nodes.keys.sort.flat_map do |from|
+        from_meta = nodes[from]
+        from_commits = from_meta[:commit_count]
+        next [] unless from_commits.is_a?(Integer)
+
+        @graph.edge_records(from, type: from_meta[:type]).filter_map do |edge|
+          volatile_entry(from, from_meta, from_commits, edge, nodes, scores)
+        end
+      end
+      entries.uniq { |e| [e[:from], e[:to], e[:via]] }
+             .sort_by { |e| [-e[:pagerank], -e[:ratio], e[:from], e[:to], e[:via]] }
+    end
+
+    # @return [Hash, nil] the report entry for one edge, or nil when it is not volatile
+    def volatile_entry(from, from_meta, from_commits, edge, nodes, scores)
+      to = edge[:target]
+      to_meta = nodes[to]
+      return nil unless to_meta
+
+      to_commits = to_meta[:commit_count]
+      return nil unless to_commits.is_a?(Integer) && to_commits >= VOLATILE_MIN_COMMITS
+      return nil if to_meta[:change_frequency] == 'new'
+
+      ratio = to_commits.to_f / [from_commits, 1].max
+      return nil if ratio < @volatile_ratio
+
+      {
+        from: from, from_type: from_meta[:type], to: to, to_type: to_meta[:type], via: edge[:via].to_s,
+        from_commits: from_commits, to_commits: to_commits,
+        ratio: ratio.round(2), pagerank: (scores[to] || 0.0).round(4)
+      }
+    end
+
+    # ──────────────────────────────────────────────────────────────────────
+    # Package boundary helpers
+    # ──────────────────────────────────────────────────────────────────────
+
+    # Short-circuits to `[]`, skipping declaration lookup entirely, when no
+    # node carries a `package` attribute (no package extraction ran).
     #
-    # @return [Hash] identifier => [dependency identifiers]
-    def graph_edges
-      @graph_edges ||= graph_data[:edges]
+    # @return [Array<Hash>]
+    def compute_undeclared_package_edges
+      nodes = graph_nodes
+      return [] unless nodes.each_value.any? { |meta| meta.key?(:package) }
+
+      declared = package_declarations(nodes)
+      entries = nodes.keys.sort.flat_map do |from|
+        meta = nodes[from]
+        from_package = meta[:package]
+        next [] if from_package.nil? || meta[:type] == :package
+
+        @graph.edge_records(from, type: meta[:type]).filter_map do |edge|
+          undeclared_entry(from, meta, from_package, edge, nodes, declared)
+        end
+      end
+      entries.uniq.sort_by { |e| [e[:from], e[:to], e[:via]] }
+    end
+
+    # package identifier => Set of package identifiers it declares as
+    # dependencies, read from that package unit's own `:package_dependency`
+    # edges. A root package (`.`) declaring nothing is just another entry
+    # with an empty Set, no special-cased root handling.
+    #
+    # @param nodes [Hash]
+    # @return [Hash{String => Set<String>}]
+    def package_declarations(nodes)
+      nodes.each_with_object({}) do |(identifier, meta), declared|
+        next unless meta[:type] == :package
+
+        declared[identifier] = @graph.dependencies_of(identifier, via: :package_dependency).to_set
+      end
+    end
+
+    # @return [Hash, nil] the report entry, or nil when the edge stays inside declared boundaries
+    def undeclared_entry(from, from_meta, from_package, edge, nodes, declared)
+      to = edge[:target]
+      to_meta = nodes[to]
+      to_package = to_meta && to_meta[:package]
+      return nil if to_package.nil? || to_package == from_package
+
+      declared_deps = declared[from_package] || Set.new
+      return nil if declared_deps.include?(to_package)
+
+      {
+        from: from, from_type: from_meta[:type], to: to, to_type: to_meta[:type], via: edge[:via].to_s,
+        from_package: from_package, to_package: to_package
+      }
     end
 
     # ──────────────────────────────────────────────────────────────────────
@@ -444,7 +813,7 @@ module Woods
       found_cycles = []
       seen_cycle_signatures = Set.new
 
-      nodes.each_key do |start_node|
+      nodes.keys.sort.each do |start_node|
         next unless color[start_node] == white
 
         # Iterative DFS using an explicit stack.
@@ -470,6 +839,9 @@ module Woods
           path.push(node)
           stack.push([node, :exit])
 
+          # Not sorted, deliberately: this list is the unit's own declared
+          # dependency order, which is identical in a full and an incremental
+          # run, so sorting it would change nothing any test can observe.
           neighbors = @graph.dependencies_of(node)
           neighbors.each do |neighbor|
             case color[neighbor]
@@ -492,6 +864,8 @@ module Woods
         end
       end
 
+      # Deterministic without a final sort: the DFS starts from a sorted
+      # node list, so cycles are discovered in the same order every run.
       found_cycles
     end